[nongnu] elpa/annotate 1a09f78be9 322/372: - added comments to local functions of 'annotate-annotate'.

[ELPA Syncer]

branch: elpa/annotate
commit 1a09f78be9e04b672e6d249d29d3b91cd6d65e77
Author: cage <cage@localhost>
Commit: cage <cage@invalid>

    - added comments to local functions of 'annotate-annotate'.
---
 annotate.el | 38 ++++++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/annotate.el b/annotate.el
index 908f44e875..a97d55c49c 100644
--- a/annotate.el
+++ b/annotate.el
@@ -567,6 +567,7 @@ specified by `from' and `to'."
   "Create, modify, or delete annotation."
   (interactive)
   (cl-labels ((create-new-annotation ()
+               ;; create a new annotation in the region returned by 
`annotate-bound'
                (cl-destructuring-bind (start end)
                    (annotate-bounds)
                  (let ((annotation-text (read-from-minibuffer 
annotate-annotation-prompt)))
@@ -575,6 +576,12 @@ specified by `from' and `to'."
                      (annotate-empty-annotation-text-error
                       (user-error "Annotation text is empty."))))))
               (cut-right (region-beg region-stop &optional delete-enclosed)
+                ;; This function will trim on the right one or more
+                ;; existing chains of overlays that compose an
+                ;; annotation (i.e. the overlays applied on the
+                ;; annotated text). After this function is called the
+                ;; text staring from `region-beg' end ending on
+                ;; `region-stop' will be cleared of all annotations.
                 (let* ((last-of-chain-to-cut  (annotate-chain-last-at 
region-beg))
                        (first-of-chain-to-cut (annotate-chain-first-at 
region-beg))
                        (chain-start           (overlay-start 
first-of-chain-to-cut))
@@ -590,6 +597,12 @@ specified by `from' and `to'."
                   (when delete-enclosed
                     (annotate-delete-chains-in-region chain-end region-stop))))
               (cut-left (region-beg region-stop &optional delete-enclosed)
+                ;; This function will trim on the left one or more
+                ;; existing chains of overlays that compose an
+                ;; annotation (i.e. the overlays applied on the
+                ;; annotated text). After this function is called the
+                ;; text staring from `region-beg' end ending on
+                ;; `region-stop' will be cleared of all annotations.
                 (let* ((last-of-chain-to-cut  (annotate-chain-last-at 
region-stop))
                        (first-of-chain-to-cut (annotate-chain-first-at 
region-stop))
                        (chain-start           (overlay-start 
first-of-chain-to-cut))
@@ -604,12 +617,25 @@ specified by `from' and `to'."
                       (annotate--cut-left-annotation last-of-chain-to-cut)))
                   (when delete-enclosed
                     (annotate-delete-chains-in-region chain-end region-stop))))
-              (annotate-overwrite-line (eol bol)
-                 (goto-char bol)
+              (annotate-overwrite-range (start end)
+                ;; annotate  text starting  from  `start'  and ending  on
+                ;; `end', overwriting any other annotation existing in
+                ;; that range
+                 (goto-char end)
                  (push-mark (point) t t)
-                 (goto-char eol)
+                 (goto-char start)
                  (annotate-annotate))
               (annotate-line (eol)
+                ;; annotate a line that terminate at `eol'
+                ;;
+                ;; if  the line  contains no  text before  the newline
+                ;; annotate the next line with text, if any
+                ;;
+                ;; if the line contains a single annotation that spans
+                ;; the whole line update the existing annotation
+                ;;
+                ;; if  the line  contains no  annotation annotate  the
+                ;; whole line that terminate at `eol'
                 (let* ((bol                     
(annotate-beginning-of-line-pos))
                        (annotations-on-the-line 
(annotate-annotations-overlay-in-range bol
                                                                                
        eol)))
@@ -626,8 +652,8 @@ specified by `from' and `to'."
                               (push-mark start-overlay t t)
                               (annotate-change-annotation (overlay-start 
annotation))
                               (pop-mark))
-                          (annotate-overwrite-line bol eol)))
-                    (annotate-overwrite-line bol eol)))))
+                          (annotate-overwrite-range bol eol)))
+                    (annotate-overwrite-range bol eol)))))
     (let ((annotation (annotate-annotation-at (point))))
       (cond
        ((use-region-p)
@@ -682,7 +708,7 @@ specified by `from' and `to'."
                 (save-excursion
                   (let* ((bol (annotate-beginning-of-line-pos))
                          (eol (point)))
-                    (if (/=  eol bol)       ; text before the newline, 
annotate it
+                    (if (/= eol bol)       ; text before the newline, annotate 
it
                         (annotate-line eol)
                       (progn                ; no text before  the new
                                             ; line, annotate next line