[nongnu] elpa/annotate 83e81e0979 369/372: - added missing docstrings and improved a bit the old ones.

[ELPA Syncer]

branch: elpa/annotate
commit 83e81e0979ac1483f93dff84e21543322cba8002
Author: cage <cage@invalid>
Commit: cage <cage@invalid>

    - added missing docstrings and improved a bit the old ones.
---
 annotate.el | 271 ++++++++++++++++++++++++++++++++----------------------------
 1 file changed, 145 insertions(+), 126 deletions(-)

diff --git a/annotate.el b/annotate.el
index 28f84ea161..5d6c126bcc 100644
--- a/annotate.el
+++ b/annotate.el
@@ -140,7 +140,7 @@ that Emacs passes to the diff program."
   :group 'annotate)
 
 (defcustom annotate-fallback-comment "#"
-  "When variable `comment-start' is nil use this string instead."
+  "When variable `COMMENT-START' is nil use this string instead."
   :type 'string
   :group 'annotate)
 
@@ -177,7 +177,7 @@ database file will be shown."
   :group 'annotate)
 
 (defcustom annotate-annotation-max-size-not-place-new-line 15
- "The maximum `string-width` allowed for an annotation to be
+ "The maximum 'string-width' allowed for an annotation to be
 placed on the right margin of the window instead of its own line
  after the annotated text."
   :type  'number
@@ -193,7 +193,7 @@ placed on the right margin of the window instead of its own 
line
   decide by text's length
 
 if the length is more than the value of
-`annotate-annotation-max-size-not-place-new-line' place the
+`ANNOTATE-ANNOTATION-MAX-SIZE-NOT-PLACE-NEW-LINE' place the
 annotation on a new line, place on the right margin
 otherwise."
   :type  'symbol
@@ -319,7 +319,7 @@ annotation as defined in the database."
   'annotate-error)
 
 (cl-defmacro annotate-with-disable-read-only (&body body)
-"Run `body' with `read-only-mode' temporary disabled."
+"Run `BODY' with `READ-ONLY-MODE' temporary disabled."
   `(let ((read-mode-p (if buffer-read-only
                           1
                         -1)))
@@ -350,11 +350,11 @@ annotation as defined in the database."
       (annotate-shutdown)))))
 
 (cl-defun annotate-buffer-checksum (&optional (object (current-buffer)))
-  "Calculate an hash for the argument `object'."
+  "Calculate an hash for the argument `OBJECT'."
   (secure-hash 'md5 object))
 
 (cl-defmacro annotate-with-inhibit-modification-hooks (&rest body)
-  "Wrap `body' in a block with modification-hooks inhibited."
+  "Wrap `BODY' in a block with modification-hooks inhibited."
   (let ((old-mode (gensym)))
     `(let ((,old-mode inhibit-modification-hooks))
        (unwind-protect
@@ -364,8 +364,8 @@ annotation as defined in the database."
          (setf inhibit-modification-hooks ,old-mode)))))
 
 (cl-defmacro annotate-with-restore-modified-bit (&rest body)
-  "Save the value of `buffer-modified-p' before `body' is executed
-and restore the saved value just after the end of `body'."
+  "Save the value of `BUFFER-MODIFIED-P' before `BODY' is executed
+and restore the saved value just after the end of `BODY'."
   (let ((modifiedp (gensym)))
     `(let ((,modifiedp (buffer-modified-p)))
        ,@body
@@ -391,36 +391,36 @@ position (so that it is unchanged after this function is 
called)."
      (overlay-end   annotation)))
 
 (defun annotate-annotation-force-newline-policy (annotation)
-  "Force annotate to place `annotation' on the line after the annotated text.
+  "Force annotate to place `ANNOTATION' on the line after the annotated text.
 
-See: `annotate-annotation-position-policy'."
+See: `ANNOTATE-ANNOTATION-POSITION-POLICY'."
   (overlay-put annotation 'force-newline-policy t))
 
 (defun annotate-annotation-newline-policy-forced-p (annotation)
-  "Is `annotation' forced  to place annotation on the  line after the
+  "Is `ANNOTATION' forced to place annotation on the line after the
 annotated text?
 
-See: `annotate-annotation-position-policy'."
+See: `ANNOTATE-ANNOTATION-POSITION-POLICY'."
   (overlay-get annotation 'force-newline-policy))
 
 (defun annotate--remap-chain-pos (annotations)
-  "Remap an annotation 'chain'.
+  "Remap `ANNOTATIONS' as an annotation 'chain'.
 
 An annotation is a collection of one or more overlays that
-contains the property `annotate-prop-chain-position'.
+contains the property `ANNOTATE-PROP-CHAIN-POSITION'.
 
-The value of `annotate-prop-chain-position' in each chain is an
+The value of `ANNOTATE-PROP-CHAIN-POSITION' in each chain is an
 integer starting from:
 
-`annotate-prop-chain-pos-marker-first' and *always* ending with
+`ANNOTATE-PROP-CHAIN-POS-MARKER-FIRST' and *always* ending with
 
-`annotate-prop-chain-pos-marker-last'
+`ANNOTATE-PROP-CHAIN-POS-MARKER-LAST'
 
 This means that a value of said property for a chain that
 contains only an element is equal to
-`annotate-prop-chain-pos-marker-last'.
+`ANNOTATE-PROP-CHAIN-POS-MARKER-LAST'.
 
-This function ensure this constrains for the chain `annotation'
+This function ensure this constrains for the chain `ANNOTATION'
 belong."
   (cond
    ((< (length annotations)
@@ -505,22 +505,22 @@ modified (for example a newline is inserted)."
                                     (1 (annotate--change-guard)))))))
 
 (defun annotate-overlay-filled-p (overlay)
-  "Does this `overlay' contains an 'annotation' property?"
+  "Does this `OVERLAY' contains an 'annotation' property?"
   (and overlay
        (overlayp overlay)
        (overlay-get overlay 'annotation)))
 
 (defun annotationp (overlay)
-  "Is `overlay' an annotation?"
+  "Is `OVERLAY' an annotation?"
   (annotate-overlay-filled-p overlay))
 
 (cl-defmacro annotate-ensure-annotation ((overlay) &body body)
-  "Runs body only if overlay is an annotation (i.e. passes annotationp)."
+  "Runs body only if `OVERLAY' is an annotation (i.e. passes annotationp)."
   `(and (annotationp ,overlay)
         (progn ,@body)))
 
 (defun annotate--position-on-annotated-text-p (pos)
-  "Does `pos' (as buffer position) corresponds to a character
+  "Does `POS' (as buffer position) corresponds to a character
 that belong to some annotated text?"
   (let ((annotation (annotate-annotation-at pos)))
     (if annotation
@@ -575,14 +575,14 @@ that belong to some annotated text?"
 
 (defun annotate-delete-chains-in-region (from to)
   "Deletes all the chains enclosed in the range specified by
-positions `from' and `to'."
+positions `FROM' and `TO'."
   (let* ((enclosed-chains (annotate-annotations-chain-in-range from to)))
     (dolist (chain enclosed-chains)
       (annotate--delete-annotation-chain (cl-first chain)))))
 
 (defun annotate-count-newline-in-region (from to)
  "Counts the number of newlines character (?\n) in range
-specified by `from' and `to'."
+specified by `FROM' and `TO'."
   (cl-count-if (lambda (a) (char-equal a ?\n))
                (buffer-substring-no-properties from to)))
 
@@ -940,13 +940,13 @@ annotation, and can be conveniently viewed in diff-mode."
 - the area between the overlay and the annotation
 - the newline that will display the annotation
 
-The first match will get `annotate--change-guard` as its
-`insert-in-front-hook`, to make sure that if a newline is inserted
-between the overlay and the annotation, the `display` property of
+The first match will get `ANNOTATE--CHANGE-GUARD' as its
+`INSERT-IN-FRONT-HOOK', to make sure that if a newline is inserted
+between the overlay and the annotation, the 'display' property of
 the newline is properly disposed of.
 
-The second match will get `annotate--annotation-builder` as its
-`display` property, which makes the newline look like an
+The second match will get `ANNOTATE--ANNOTATION-BUILDER' as its
+'display' property, which makes the newline look like an
 annotation plus the newline."
   (goto-char (next-overlay-change (point)))
   (if (>= (point) limit)
@@ -973,8 +973,8 @@ annotation plus the newline."
   start-word)
 
 (defun annotate-group-by-width (text maximum-width)
-  "Groups text in a list formed by chunks of maximum size equal
-to 'maximum-width'."
+  "Groups `TEXT' in a list formed by chunks of maximum size equal
+to `MAXIMUM-WIDTH'."
   (cl-labels ((next-word (words)
                          (or (cl-first words)
                              ""))
@@ -1047,7 +1047,8 @@ to 'maximum-width'."
         grouped))))
 
 (cl-defun annotate-safe-subseq (seq from to &optional (value-if-limits-invalid 
seq))
-  "Returns 'value-if-limits-invalid' sequence if 'from' or 'to' are invalids."
+  "Returns a substring of `SEQ' or `VALUE-IF-LIMITS-INVALID'
+sequence if `FROM' or `TO' are invalids."
   (cond
    ((< to from)
     value-if-limits-invalid)
@@ -1059,7 +1060,7 @@ to 'maximum-width'."
     (cl-subseq seq from to))))
 
 (defun annotate-lineate (text line-width)
-  "Breaks `text` into lines to fit in the annotation space."
+  "Breaks `TEXT' into lines to fit in the annotation space with width 
`LINE-WIDTH'."
   (cl-labels ((pad (string max-width add-newline-p)
                    (if (null string)
                        ""
@@ -1097,12 +1098,12 @@ to 'maximum-width'."
                      (list (pad last-line max-width nil)))))))
 
 (cl-defun annotate--split-lines (text &optional (separator "\n"))
-  "Returns text splitted by `separator' (default: \"\n\")."
+  "Returns `TEXT' splitted by `SEPARATOR' (default: \"\n\")."
   (save-match-data
     (split-string text separator)))
 
 (defun annotate--join-with-string (strings junction)
-"Join list of string in `strings' using string `junction'."
+"Join list of string in `STRINGS' using string `JUNCTION'."
   (cl-reduce (lambda (a b) (concat a junction b))
              strings))
 
@@ -1110,12 +1111,13 @@ to 'maximum-width'."
                                         begin-of-line
                                         end-of-line
                                         annotation-on-is-own-line-p)
-  "Pads   or    breaks   annotation   text   (as    property   of
-`annotation-overlay' so that all lines have the same width.
+  "Pads or breaks annotation text (as property of
+`ANNOTATION-OVERLAY' so that all lines have the same width.
 
-If annotation is a  placed on the margin of a window (that is  
`annotation-on-is-own-line-p' is
-nil) the text is broken (regardless  of words) to fit on the side
-of the window using `begin-of-line' `end-of-line'.
+If annotation is a placed on the margin of a window (that is
+`ANNOTATION-ON-IS-OWN-LINE-P' is
+nil) the text is broken (regardless of words) to fit on the side
+of the window using `BEGIN-OF-LINE' `END-OF-LINE'.
 
 If annotation is a note that is placed in its own line the text is padded with 
spaces so that
 a 'box' surround the text without seams, e.g:
@@ -1152,7 +1154,7 @@ a        a**"
 
 (defun annotate--annotation-builder ()
   "Searches the line before point for annotations, and returns a
-`facespec` with the annotation in its `display` property."
+'facespec' with the annotation in its 'display' property."
   (save-excursion
     (let ((newline-position (point)))
       (goto-char (1- (point))) ; we start at the start of the previous line
@@ -1250,7 +1252,8 @@ a        a**"
             (list 'face 'default 'display annotation-text)))))))
 
 (defun annotate--remove-annotation-property (begin end)
-  "Cleans up annotation properties associated with a region."
+  "Cleans up annotation properties associated within a region
+surrounded by `BEGIN' and `END'."
   (when (and (> (buffer-size) 0)
              (not (buffer-narrowed-p)))
     (annotate-with-inhibit-modification-hooks
@@ -1272,7 +1275,7 @@ a        a**"
 
 (defun annotate-annotations-overlay-in-range (from-position to-position)
   "Returns the annotations overlays that are enclosed in the range
-defined by `from-position' and `to-position'."
+defined by `FROM-POSITION' and `TO-POSITION'."
   (let ((annotations ()))
     (cl-loop for  i
              from (max 0 (1- from-position))
@@ -1289,7 +1292,7 @@ defined by `from-position' and `to-position'."
 
 (defun annotate-annotations-chain-in-range (from-position to-position)
   "Returns the annotations (chains) that are enclosed in the range
-defined by `from-position' and `to-position'."
+defined by `FROM-POSITION' and `TO-POSITION'."
   (let ((annotations (annotate-annotations-overlay-in-range from-position 
to-position))
         (chains      ()))
     (cl-loop for annotation in annotations do
@@ -1308,7 +1311,9 @@ an overlay and it's annotation."
         '(annotate--remove-annotation-property)))
 
 (defun annotate-prefix-lines (prefix text &optional omit-trailing-null)
-  "Prepend PREFIX to each line in TEXT."
+ "Prepend `PREFIX' to each line in `TEXT'.
+If `OMIT-TRAILING-NULL' is non null, empty line at the end of
+text will be discarded."
   (let ((lines (annotate--split-lines text "\n")))
     (when omit-trailing-null
       (let ((last-not-empty (cl-position-if-not 'annotate-string-empty-p
@@ -1332,7 +1337,7 @@ buffer is not on info-mode"
 
 (cl-defun annotate-guess-filename-for-dump (filename
                                             &optional 
(return-filename-if-not-found-p t))
-  "Prepare an acceptable filename suitable for metadata database."
+  "Guess an acceptable file name suitable for metadata database from 
`FILENAME'."
   (cond
    ((annotate-string-empty-p filename)
     nil)
@@ -1351,7 +1356,7 @@ buffer is not on info-mode"
       found))))
 
 (defun annotate-make-annotation-dump-entry (filename file-annotations checksum)
-  "Make an annotation record: see `annotate-load-annotations'."
+  "Make an annotation record: see `ANNOTATE-LOAD-ANNOTATIONS'."
   (list filename
         file-annotations
         checksum))
@@ -1391,17 +1396,20 @@ essentially what you get from:
   (cl-second annotation))
 
 (defun annotate--interval-left-limit (a)
+  "Given an annotation record `A' returns the left limit of the annotated 
text."
   (cl-first a))
 
 (defun annotate--interval-right-limit (a)
+  "Given an annotation record `A' returns the right limit of the annotated 
text."
   (cl-second a))
 
 (defun annotate--make-interval (left-limit right-limit)
+  "Make an interval from `LEFT-LIMIT' and `RIGHT-LIMIT'."
   (list left-limit right-limit))
 
 (defun annotate-annotation-interval (annotation)
-  "Returns a list of two  numbers representing the left and right
-limit  respectively  of the  portion  of  the buffer  where  this
+  "Returns a list of two numbers representing the left and right
+limit respectively of the portion of the buffer where this
 annotation is applied.
 Note that this function returns the character interval
 yyyyyyyy ggg
@@ -1421,7 +1429,7 @@ essentially what you get from:
   (nth 2 annotation))
 
 (defun annotate-annotated-text (annotation)
-  "Get the annotated text of an annotation. The arg 'annotation' must be a 
single
+  "Get the annotated text of an annotation. The arg `ANNOTATION' must be a 
single
 annotation field got from a file dump of all annotated buffers,
 essentially what you get from:
 \(annotate-annotations-from-dump (nth index (annotate-load-annotations))))."
@@ -1557,7 +1565,7 @@ example:
           (message "Annotations loaded."))))))
 
 (defun annotate-db-clean-records (records-db)
-  "Remove records from arg `records-db' that have empty annotation, example:
+  "Remove records from arg `RECORDS-DB' that have empty annotation, example:
 
 '((\"/foo/bar.dat\" nil \"abababababababababababababab\")
   (\"/foo/baz.dat\" ((0 9 \"note\" \"annotated\")) 
\"abababababababababababababab\"))
@@ -1578,7 +1586,7 @@ annotation."
     (annotate-dump-annotation-data db)))
 
 (defun annotate--expand-record-path (record)
-"Expand file component of `record'."
+"Expand file component of `RECORD'."
   (let* ((short-filename  (annotate-filename-from-dump    record))
          (annotations     (annotate-annotations-from-dump record))
          (file-checksum   (annotate-checksum-from-dump    record))
@@ -1592,6 +1600,7 @@ annotation."
                           file-checksum)))
 
 (defun annotate--deserialize-database-file (file)
+"Returns a sexp from the annotation database contained in `FILE'."
   (with-temp-buffer
     (let* ((annotations-file file)
            (attributes    (file-attributes annotations-file)))
@@ -1612,7 +1621,7 @@ annotation."
       (annotate--deserialize-database-file annotate-file)))
 
 (defun annotate-dump-annotation-data (data &optional save-empty-db)
-  "Save `data' into annotation file."
+  "Save `DATA' into annotation file."
   (cond
    ((or save-empty-db
         data)
@@ -1659,9 +1668,9 @@ annotation."
                                       record-filename
                                       annotation-beginning
                                       annotation-ending)
-  "Remove from database `db-records' the annotation identified by
-the triplets `record-filename', `annotation-beginning' and
- `annotation-ending'; if such annotation does exists."
+  "Remove from database `DB-RECORDS' the annotation identified by
+the triplets `RECORD-FILENAME', `ANNOTATION-BEGINNING' and
+ `ANNOTATION-ENDING'; if such annotation does exists."
   (with-matching-annotation-fns
    (record-filename
     annotation-beginning
@@ -1684,9 +1693,9 @@ the triplets `record-filename', `annotation-beginning' and
                                        annotation-beginning
                                        annotation-ending
                                        replacing-text)
-  "Replace the text of annotation from database `db-records'
-identified by the triplets `record-filename',
- `annotation-beginning' and `annotation-ending'; if such
+  "Replace the text of annotation from database `DB-RECORDS'
+identified by the triplets `RECORD-FILENAME',
+ `ANNOTATION-BEGINNING' and `ANNOTATION-ENDING'; if such
  annotation does exists."
   (with-matching-annotation-fns
    (record-filename
@@ -1715,7 +1724,7 @@ identified by the triplets `record-filename',
        db-records))))
 
 (defun annotate-db-annotations-starts-before-p (a b)
-  "Non nil if  annotation `a' starts before `b'.
+  "Non nil if  annotation `A' starts before `B'.
 
 In this context annotation means annotation loaded from local
 database not the annotation shown in the buffer (therefore these
@@ -1743,34 +1752,34 @@ functions)."
       (set-buffer-modified-p modifiedp))))
 
 (defun annotate-string-empty-p (a)
-  "Is the arg an empty string or null?"
+  "Is the arg `A' an empty string or null?"
   (or (null a)
       (string= "" a)))
 
 (defun annotate-annotation-prop-get (annotation property)
-  "Get  property  `property'  from  annotation  `annotation'.  If
-`annotation' does not pass `annotationp' returns nil."
+  "Get property `PROPERTY' from annotation `ANNOTATION'. If
+`ANNOTATION' does not pass `annotationp' returns nil."
   (annotate-ensure-annotation (annotation)
     (overlay-get annotation property)))
 
 (defun annotate-annotation-get-chain-position (annotation)
-  "Get property's value that  define position of this annotation
+  "Get property's value that define position of this annotation
 in a chain of annotations"
   (annotate-annotation-prop-get annotation annotate-prop-chain-position))
 
 (defun annotate-annotation-chain-position (annotation pos)
-  "Set property's value that  define position of this annotation
+  "Set property's value that define position of this annotation
 in a chain of annotations."
   (overlay-put annotation annotate-prop-chain-position pos))
 
 (defun annotate-chain-last-p (annotation)
-  "Non nil if this annotation is the last element of a chain of annotations."
+  "Non nil if `ANNOTATION' is the last element of a chain of annotations."
   (let ((value (annotate-annotation-get-chain-position annotation)))
     (and value
          (cl-equalp value annotate-prop-chain-pos-marker-last))))
 
 (defun annotate-chain-first-p (annotation)
-  "Non nil if  this annotation is the first element,  or the only
+  "Non nil if `ANNOTATION' is the first element, or the only
 of a chain of annotations."
   (let* ((chain-pos           (annotate-annotation-get-chain-position 
annotation))
          (annotation-start    (overlay-start annotation))
@@ -1785,7 +1794,7 @@ of a chain of annotations."
                     annotate-prop-chain-pos-marker-last))))))
 
 (defun annotate-chain-first (annotation)
-  "Find first element of the chain where `annotation' belongs."
+  "Find first element of the chain where `ANNOTATION' belongs."
   (cond
    ((null annotation)
     nil)
@@ -1797,7 +1806,7 @@ of a chain of annotations."
       (annotate-chain-first previous-annotation)))))
 
 (defun annotate-chain-last (annotation)
-  "Find last element of the chain where `annotation' belongs."
+  "Find last element of the chain where `ANNOTATION' belongs."
   (cond
    ((null annotation)
     nil)
@@ -1809,35 +1818,35 @@ of a chain of annotations."
       (annotate-chain-last next-annotation)))))
 
 (defun annotate-chain-first-at (pos)
-  "Find first element of the chain of annotation that overlap point `pos'."
+  "Find first element of the chain of annotation that overlap point `POS'."
   (let ((annotation (annotate-annotation-at pos)))
     (annotate-ensure-annotation (annotation)
       (annotate-chain-first annotation))))
 
 (defun annotate-chain-last-at (pos)
-  "Find last element of the chain of annotation that overlap point `pos'."
+  "Find last element of the chain of annotation that overlap point `POS'."
   (let ((annotation (annotate-annotation-at pos)))
     (annotate-ensure-annotation (annotation)
       (annotate-chain-last annotation))))
 
 (defun annotate-chain-at (pos)
-  "Find the chain of overlays where point `pos' belongs."
+  "Find the chain of overlays where point `POS' belongs."
   (let ((annotation (annotate-annotation-at pos)))
     (annotate-ensure-annotation (annotation)
       (annotate-find-chain annotation))))
 
 (defun annotate-annotation-set-chain-first (annotation)
-  "Set property's value that  define position of this annotation
+  "Set property's value that define position of this annotation
 in a chain of annotations as first."
   (annotate-annotation-chain-position annotation 
annotate-prop-chain-pos-marker-first))
 
 (defun annotate-annotation-set-chain-last (annotation)
-  "Set property's value that  define position of this annotation
+  "Set property's value that define position of this annotation
 in a chain of annotations as last."
   (annotate-annotation-chain-position annotation 
annotate-prop-chain-pos-marker-last))
 
 (defun annotate-find-chain (annotation)
-  "Find all annotation that are parts of the chain where `annotation' belongs."
+  "Find all ANNOTATION that are parts of the chain where `ANNOTATION' belongs."
   (annotate-ensure-annotation (annotation)
     (cl-labels ((find-next-annotation (pos)
                  (annotate-annotation-at (next-overlay-change pos))))
@@ -2014,23 +2023,23 @@ The searched interval can be customized setting the 
variable:
           (font-lock-fontify-block 1))))))
 
 (defun annotate-overlay-put-echo-help (overlay text)
-  "Set the property `help-echo' to `text' in overlay `overlay'."
+  "Set the property `HELP-ECHO' to `TEXT' in overlay `OVERLAY'."
   (overlay-put overlay 'help-echo text))
 
 (defun annotate-overlay-get-echo-help (overlay)
-  "Set the property `help-echo' from overlay `overlay'."
+  "Set the property `HELP-ECHO' from overlay `OVERLAY'."
   (overlay-get overlay 'help-echo))
 
 (defun annotate-overlay-maybe-set-help-echo (overlay annotation-text)
-  "Set the property `help-echo' to `text' in overlay `overlay' if
+  "Set the property `HELP-ECHO' to `TEXT' in overlay `OVERLAY' if
 the annotations should be shown in a popup fashion.
 
-See the variable: `annotate-use-echo-area'."
+See the variable: `ANNOTATE-USE-ECHO-AREA'."
   (when annotate-use-echo-area
     (annotate-overlay-put-echo-help overlay annotation-text)))
 
 (defun annotate--delete-annotation-chain (annotation)
-  "Delete `annotation' from a buffer and the chain it belongs to.
+  "Delete `ANNOTATION' from a buffer and the chain it belongs to.
 
 This function is not part of the public API."
   (annotate-ensure-annotation (annotation)
@@ -2046,7 +2055,7 @@ This function is not part of the public API."
            (delete-overlay single-element)))))))
 
 (defun annotate--delete-annotation-chain-ring (annotation-ring)
-  "Delete overlay of `annotation-ring' from a buffer.
+  "Delete overlay of `ANNOTATION-RING' from a buffer.
 
 A ring is a single element of an annotation chain.
 
@@ -2060,8 +2069,8 @@ This function is not part of the public API."
       (delete-overlay annotation-ring))))
 
 (defun annotate-delete-chain-element (annotation)
-  "Delete a ring (a ring is a single element of an annotation chain.)
-from a chain where `annotation' belong."
+  "Delete a ring (a ring is a single element of an ANNOTATION chain.)
+from a chain where `ANNOTATION' belong."
   (annotate-ensure-annotation (annotation)
     (let* ((chain                   (annotate-find-chain    annotation))
            (first-of-chain-p        (annotate-chain-first-p annotation))
@@ -2079,7 +2088,7 @@ from a chain where `annotation' belong."
             (annotate-annotation-set-chain-last annotation-before))))))))
 
 (defun annotate--cut-left-annotation (annotation)
-  "Trims `annotation' exactly one character from the start."
+  "Trims `ANNOTATION' exactly one character from the start."
   (annotate-ensure-annotation (annotation)
     (let* ((chain                       (annotate-find-chain annotation))
            (first-annotation            (annotate-chain-first annotation))
@@ -2097,7 +2106,7 @@ from a chain where `annotation' belong."
         (move-overlay first-annotation new-starting-pos 
first-annotation-ending-pos))))))
 
 (defun annotate--cut-right-annotation (annotation &optional refontify-buffer)
-  "Trims `annotation' exactly one character from the end."
+  "Trims `ANNOTATION' exactly one character from the end."
   (annotate-ensure-annotation (annotation)
     (let* ((chain                        (annotate-find-chain annotation))
            (last-annotation              (annotate-chain-last annotation))
@@ -2132,8 +2141,8 @@ This function is not part of the public API."
       (y-or-n-p annotate-confirm-deleting-annotation-prompt)))
 
 (cl-defun annotate-delete-annotation (&optional (point (point)))
-  "Command  to  delete  an  annotation,  `point'  is  the  buffer
-position  where  to  look  for  annotation  (default  the  cursor
+  "Command to delete an annotation, `POINT' is the buffer
+position where to look for annotation (default the cursor
 point)."
   (interactive)
   (when-let ((annotation (annotate-annotation-at point)))
@@ -2177,7 +2186,7 @@ point)."
 
 (defun annotate-annotation-at (pos)
   "Returns the annotations (overlay where (annotationp overlay) -> t)
-at positions pos or nil if no annotations exists at pos.
+at positions `POS' or nil if no annotations exists at pos.
 
 NOTE this assumes that annotations never overlaps so the list of
 all annotations can contains only one element maximum."
@@ -2186,7 +2195,7 @@ all annotations can contains only one element maximum."
     (cl-first all)))
 
 (defun annotate-previous-annotation-ends (pos)
-  "Returns the previous annotation that ends before pos or nil if no annotation
+  "Returns the previous annotation that ends before `POS' or nil if no 
annotation
 was found.
 NOTE this assumes that annotations never overlaps."
   (cl-labels ((previous-annotation-ends (start)
@@ -2203,12 +2212,12 @@ NOTE this assumes that annotations never overlaps."
         (previous-annotation-ends pos)))))
 
 (defun annotate-previous-annotation (annotation)
- "Returns the annotation before `annotations' or nil if no such
+ "Returns the annotation before `ANNOTATIONS' or nil if no such
 annotation exists."
  (annotate-previous-annotation-ends (overlay-start (annotate-chain-first 
annotation))))
 
 (defun annotate-next-annotation-starts (pos)
-  "Returns the previous annotation that ends before pos or nil if no annotation
+  "Returns the previous annotation that ends before `POS' or nil if no 
annotation
 was found.
 NOTE this assumes that annotations never overlaps."
   (cl-labels ((next-annotation-ends (start)
@@ -2225,13 +2234,13 @@ NOTE this assumes that annotations never overlaps."
         (next-annotation-ends pos)))))
 
 (defun annotate-next-annotation (annotation)
- "Returns the annotation after `annotations' or nil if no such
+ "Returns the annotation after `ANNOTATIONS' or nil if no such
 annotation exists."
  (annotate-next-annotation-starts (overlay-end (annotate-chain-last 
annotation))))
 
 (defun annotate-symbol-strictly-at-point ()
  "Returns non nil if a symbol is at char immediately following
-the point. This is needed as `thing-at-point' family of
+the point. This is needed as `THING-AT-POINT' family of
  functions returns non nil if the thing (a symbol in this case)
  is around the point, according to the documentation."
   (cl-labels ((after-point ()
@@ -2286,8 +2295,8 @@ the point. This is needed as `thing-at-point' family of
 
 (defun annotate-make-annotation (beginning ending annotation annotated-text)
  "Make an annotation record that represent an annotation
-starting at `beginning', terminate at `ending' with annotation
-content `annotation' and annotated text `annotated-text'."
+starting at `BEGINNING', terminate at `ENDING' with annotation
+content `ANNOTATION' and annotated text `ANNOTATED-TEXT'."
   (list beginning ending annotation annotated-text))
 
 (defun annotate-all-annotations ()
@@ -2403,7 +2412,7 @@ sophisticated way than plain text."
           (goto-char (button-get button 'go-to))))))))
 
 (defun annotate-update-visited-buffer-maybe (filename)
-"Reload annotation mode in  the buffer visiting `filename', if such buffer 
exists."
+"Reload annotation mode in the buffer visiting `FILENAME', if such buffer 
exists."
   (let ((visited-buffer (find-buffer-visiting filename)))
     (when visited-buffer ;; a buffer is visiting the file
       (with-current-buffer visited-buffer
@@ -2455,11 +2464,11 @@ pressed."
         (annotate-show-annotation-summary query nil nil)))))
 
 (cl-defun annotate-wrap-text (text &optional (wrapper "\""))
-  "Wrap string `text' with string `wrapper'."
+  "Wrap string `TEXT' with string `WRAPPER'."
   (concat wrapper text wrapper))
 
 (cl-defun annotate-unwrap-text (text &optional (wrapper "\"") (left-side t))
-  "Remove `wrapper' at both ends from `text'."
+  "Remove `WRAPPER' at both ends from `TEXT'."
   (let ((results        text)
         (wrapper-length (length wrapper)))
     (when (>= (length text)
@@ -2480,7 +2489,7 @@ pressed."
 (cl-defun annotate-show-annotation-summary (&optional arg-query 
cut-above-point (save-annotations t))
  "Show a summary of all the annotations in a temp buffer, the
 results can be filtered with a simple query language: see
-`annotate-summary-filter-db'."
+`ANNOTATE-SUMMARY-FILTER-DB'."
   (interactive)
   (cl-labels ((ellipsize (text prefix-string)
                          (let* ((prefix-length   (string-width prefix-string))
@@ -2654,7 +2663,7 @@ results can be filtered with a simple query language: see
 summary window is shown.")
 
 (defvar annotate-summary-query-current-token nil
-  "Holds the next token of the query in `annotate-summary-query'.")
+  "Holds the next token of the query in `ANNOTATE-SUMMARY-QUERY'.")
 
 (defun annotate-summary-query-lexer-symbol (res)
   "The symbol identifying the token (e.g. 'and)."
@@ -2666,20 +2675,20 @@ summary window is shown.")
 
 (defun annotate-summary-query-lexer-start (res)
  "The starting point of the substring of
-`annotate-summary-query' for this token."
+`ANNOTATE-SUMMARY-QUERY' for this token."
   (elt res 2))
 
 (defun annotate-summary-query-lexer-end (res)
   "The ending point of the substring of
-`annotate-summary-query' for this token."
+`ANNOTATE-SUMMARY-QUERY' for this token."
 
   (elt res 3))
 
 (cl-defun annotate-summary-lexer (&optional (look-ahead-p nil))
-  "The lexer for `annotate-summary-query'.
+  "The lexer for `ANNOTATE-SUMMARY-QUERY'.
 
 This function, when called, will produce the next token from
-`annotate-summary-query'; a token is a substring with a well
+`ANNOTATE-SUMMARY-QUERY'; a token is a substring with a well
 defined meaning according to our grammar.
 
 For example this string:
@@ -2704,13 +2713,13 @@ The format is a proper list where:
    - 'and , 'or , 'not    = logical operator
    - 'open-par, close-par = open and closing parenthesis respectively
 - second element
-  the  value (the actual substring for this token)
+  the value (the actual substring for this token)
 
 - third and fourth element (currently unused)
  the substring limits for this token (as returned by
- `match-beginning' and `match-end'
+ `MATCH-BEGINNING' and `MATCH-END'
 
-Note that spaces are ignored and all the tokens except `re' must
+Note that spaces are ignored and all the tokens except `RE' must
 not be prefixed with a backslash to match. So, for example not ->
 will match the token type 'not but \not will match the token 're;
 this way we can 'protect' a regexp that contains reserved
@@ -2719,14 +2728,14 @@ keyword (aka escaping).
 The special value :no-more-token is returned after the whole
 input is processed.
 
-Calling this function with value of `look-ahead-p' nil will `consume' the 
token from
-`annotate-summary-query' (i.e. that string is modified)
+Calling this function with value of `LOOK-AHEAD-P' nil will `CONSUME' the 
token from
+`ANNOTATE-SUMMARY-QUERY' (i.e. that string is modified)
 
 example:
 'a and b' -> 'and b', '(re \"a\" 0 1)
 
-when `look-ahead-p' is not nil the token is recognized but not cut away from
-`annotate-summary-query'
+when `LOOK-AHEAD-P' is not nil the token is recognized but not cut away from
+`ANNOTATE-SUMMARY-QUERY'
 
 example:
 'a and b' -> 'a and b', '(re \"a\" 0 1)"
@@ -2773,12 +2782,12 @@ example:
           res)))))
 
 (defun annotate-summary-query-parse-end-input-p (token)
- "Non nil if there are no more tokens in `annotate-summary-query'."
+  "Non nil if there are no more tokens in `ANNOTATE-SUMMARY-QUERY'."
   (eq token :no-more-tokens))
 
 (defun annotate-summary-token-symbol-match (looking-symbol token)
- "Return non nil if `looking-symbol' is 'eq' to the symbol
-component of `token'."
+  "Return non nil if `LOOKING-SYMBOL' is 'eq' to the symbol
+component of `TOKEN'."
   (eq looking-symbol
       (annotate-summary-query-lexer-symbol token)))
 
@@ -2809,8 +2818,8 @@ Arguments:
 
 - filter-fn is a function that accept two parameters: the regular
   expression to match (a token of type 're, see the lexer
-  `annotate-summary-lexer' and a single annotation record (see
-  `annotate-load-annotations').
+  `ANNOTATE-SUMMARY-LEXER' and a single annotation record (see
+  `ANNOTATE-LOAD-ANNOTATIONS').
 
   This function will reject (its value is nil) records that do
   not match the annotation.
@@ -2969,7 +2978,7 @@ NOT        := 'not'
 DELIMITER  := \" ; ASCII 34 (dec) 22 (hex)
 
 Note: this function returns the annotation part of the record, see
-`annotate-load-annotations'."
+`ANNOTATE-LOAD-ANNOTATIONS'."
   (lambda (annotation query file-filter-fn note-filter-fn)
     (let ((annotate-summary-query query) ; save the query
           (query-notes-only       nil)) ; the query for just the notes
@@ -3060,7 +3069,7 @@ Note: this function returns the annotation part of the 
record, see
 (defun annotate-summary-filter-db (annotations-dump query 
remove-annotations-cutoff-point)
   "Filter an annotation database with a query.
 
-The argument `query' is a string that respect a simple syntax:
+The argument `QUERY' is a string that respect a simple syntax:
 
 - [file-mask] [(and | or) [not] regex-note [(and | or) [not] regexp-note ...]]
 
@@ -3074,27 +3083,27 @@ where
 Examples:
 
 - lisp$ and TODO
- matches the text `TODO' in all lisp files
+ matches the text 'TODO' in all lisp files
 
 Parenthesis can be used for the expression related to the text of
 annotation, like this:
 
 - lisp$ and (TODO or important)
- the same as above but checks also for string `important'
+ the same as above but checks also for string 'important'
 
 - /home/foo/
  matches all the annotation that refers to file in the directory
- `/home/foo'
+ '/home/foo'
 
 - /home/foo/ and not minor
  matches all the annotation that refers to file in the directory
- `/home/foo' and that not contains the text `minor'.
+ '/home/foo' and that not contains the text 'minor'.
 
 - .* and \"not\"
  the \" can be used to escape strings
 
 If you want to remove from summary the annotations that appears
-before a position in buffer set `remove-annotations-cutoff-point' to said
+before a position in buffer set 'remove-annotations-cutoff-point' to said
 position.
 
 The annotations in each record are sorted by starting point in ascending 
order."
@@ -3167,11 +3176,11 @@ annotate minor mode active."
 refresh all the annotations contained in each buffer where
 annotate minor mode is active.
 
-if `database-file-path' is nil (the default) a prompt asking for
+if `DATABASE-FILE-PATH' is nil (the default) a prompt asking for
 a file containing database is presented to the user, otherwise
 the value of this argument is used.
 
-If `force-load' is non nil no prompt asking user for confirmation
+If `FORCE-LOAD' is non nil no prompt asking user for confirmation
 about loading the new file is shown.
 
 Note: this function will attempt to load (compile and
@@ -3208,6 +3217,9 @@ code, always use load files from trusted sources!"
 ;;; merging database
 
 (defun annotate--merge-interval (a b)
+"Merge two annotation interval `A' and `B'.
+
+The new interval is expanded so that includes `A' and `B'."
   (let ((new-left-limit  (min (annotate--interval-left-limit a)
                               (annotate--interval-left-limit b)))
         (new-right-limit (max (annotate--interval-right-limit a)
@@ -3216,6 +3228,7 @@ code, always use load files from trusted sources!"
                              new-right-limit)))
 
 (defun annotate--db-annotations-overlaps-p (annotation-a annotation-b)
+"Returns non nil if `ANNOTATION-A' and `ANNOTATION-B' overlaps."
   (let ((interval-a (annotate-annotation-interval annotation-a))
         (interval-b (annotate-annotation-interval annotation-b)))
     (not (or (< (annotate--interval-right-limit interval-b)
@@ -3224,6 +3237,7 @@ code, always use load files from trusted sources!"
                 (annotate--interval-right-limit interval-a))))))
 
 (defun annotate--db-merge-annotations (host guest)
+"Merge annotation `GUEST' into annotation `HOST' using 
`ANNOTATE--MERGE-INTERVAL'."
   (when (annotate--db-annotations-overlaps-p host guest)
     (let* ((interval-host       (annotate-annotation-interval host))
            (interval-guest      (annotate-annotation-interval guest))
@@ -3238,6 +3252,8 @@ code, always use load files from trusted sources!"
       (annotate-make-annotation left right new-annotation-text 
new-annotated-text))))
 
 (defun annotate--db-remove-overlap-annotations (annotations &optional accum)
+"Recursively merges overlapping annotations in `ANNOTATIONS'
+using `ANNOTATE--DB-MERGE-ANNOTATIONS'."
   (if (= (length annotations) 1)
       (push (cl-first annotations) accum)
     (let* ((probe            (cl-first annotations))
@@ -3258,6 +3274,7 @@ code, always use load files from trusted sources!"
         (annotate--db-remove-overlap-annotations rest-annotations (push probe 
accum))))))
 
 (defun annotate--db-merge-databases (db-1 db-2 &optional accum)
+"Recursively merge database `DB-1' and `DB-2'."
   (cl-labels ((find-same-file-record (record annotations-db)
                 (let ((record-filename (annotate-filename-from-dump record)))
                   (cl-find-if (lambda (a)
@@ -3290,6 +3307,8 @@ code, always use load files from trusted sources!"
                                         (push first-record accum)))))))
 
 (defun annotate-import-annotations ()
+"Prompt user for an annotation database file and merge it int
+their personal database."
   (interactive)
   (cl-flet ((deserialize-db (file)
              (ignore-errors (annotate--deserialize-database-file file)))