* textmodes/reftex-cite.el (reftex-cite-regexp-hist)

(reftex-citation-prompt, reftex-default-bibliography)
(reftex-bib-or-thebib, reftex-get-bibfile-list)
(reftex-pop-to-bibtex-entry, reftex-extract-bib-entries)
(reftex-bib-sort-author, reftex-bib-sort-year)
(reftex-bib-sort-year-reverse, reftex-get-crossref-alist)
(reftex-extract-bib-entries-from-thebibliography)
(reftex-get-bibkey-default, reftex-get-bib-names)
(reftex-parse-bibtex-entry, reftex-get-bib-field)
(reftex-format-bib-entry, reftex-parse-bibitem)
(reftex-format-bibitem, reftex-do-citation)
(reftex-figure-out-cite-format, reftex-offer-bib-menu)
(reftex-restrict-bib-matches, reftex-extract-bib-file)
(reftex-insert-bib-matches, reftex-format-citation)
(reftex-make-cite-echo-string, reftex-bibtex-selection-callback)
(reftex-create-bibtex-file): Add docstrings, mostly by converting
existing comments into docstrings.

3 files changed, 157 insertions, 146 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 5abb3b1b1bc..18f225ec308 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,23 @@
+2013-06-12  Rüdiger Sonderfeld  <ruediger@c-plusplus.de>
+
+        * textmodes/reftex-cite.el (reftex-cite-regexp-hist)
+        (reftex-citation-prompt, reftex-default-bibliography)
+        (reftex-bib-or-thebib, reftex-get-bibfile-list)
+        (reftex-pop-to-bibtex-entry, reftex-extract-bib-entries)
+        (reftex-bib-sort-author, reftex-bib-sort-year)
+        (reftex-bib-sort-year-reverse, reftex-get-crossref-alist)
+        (reftex-extract-bib-entries-from-thebibliography)
+        (reftex-get-bibkey-default, reftex-get-bib-names)
+        (reftex-parse-bibtex-entry, reftex-get-bib-field)
+        (reftex-format-bib-entry, reftex-parse-bibitem)
+        (reftex-format-bibitem, reftex-do-citation)
+        (reftex-figure-out-cite-format, reftex-offer-bib-menu)
+        (reftex-restrict-bib-matches, reftex-extract-bib-file)
+        (reftex-insert-bib-matches, reftex-format-citation)
+        (reftex-make-cite-echo-string, reftex-bibtex-selection-callback)
+        (reftex-create-bibtex-file): Add docstrings, mostly by converting
+        existing comments into docstrings.
+
 2013-06-12  Xue Fuqiao  <xfq.free@gmail.com>
 
         * ibuf-ext.el (ibuffer-mark-help-buffers): Doc fix.
diff --git a/lisp/textmodes/reftex-cite.el b/lisp/textmodes/reftex-cite.el
index ca29709de2e..6c103294a06 100644
--- a/lisp/textmodes/reftex-cite.el
+++ b/lisp/textmodes/reftex-cite.el
@@ -25,18 +25,16 @@
 ;;; Code:
 
 (eval-when-compile (require 'cl))
-(provide 'reftex-cite)
-(require 'reftex)
-;;;
 
-;; Variables and constants
+(require 'reftex)
 
-;; The history list of regular expressions used for citations
-(defvar reftex-cite-regexp-hist nil)
+;;; Variables and constants
+(defvar reftex-cite-regexp-hist nil
+  "The history list of regular expressions used for citations")
 
-;; Prompt and help string for citation selection
 (defconst reftex-citation-prompt
-  "Select: [n]ext [p]revious [r]estrict [ ]full_entry [q]uit RET [?]Help+more")
+  "Select: [n]ext [p]revious [r]estrict [ ]full_entry [q]uit RET [?]Help+more"
+  "Prompt and help string for citation selection")
 
 (defconst reftex-citation-help
   " n / p      Go to next/previous entry (Cursor motion works as well).
@@ -51,8 +49,7 @@
  e / E      Create BibTeX file with all (marked/unmarked) entries
  a / A      Put all (marked) entries into one/many \\cite commands.")
 
-;; Find bibtex files
-
+;;; Find bibtex files
 (defmacro reftex-with-special-syntax-for-bib (&rest body)
   `(let ((saved-syntax (syntax-table)))
      (unwind-protect
@@ -62,8 +59,8 @@
        (set-syntax-table saved-syntax))))
 
 (defun reftex-default-bibliography ()
-  ;; Return the expanded value of `reftex-default-bibliography'.
-  ;; The expanded value is cached.
+  "Return the expanded value of variable `reftex-default-bibliography'.
+The expanded value is cached."
   (unless (eq (get 'reftex-default-bibliography :reftex-raw)
               reftex-default-bibliography)
     (put 'reftex-default-bibliography :reftex-expanded
@@ -74,9 +71,8 @@
   (get 'reftex-default-bibliography :reftex-expanded))
 
 (defun reftex-bib-or-thebib ()
-  ;; Tests if BibTeX or \begin{thebibliography} should be used for the
-  ;; citation
-  ;; Find the bof of the current file
+  "Test if BibTeX or \begin{thebibliography} should be used for the citation.
+Find the bof of the current file"
   (let* ((docstruct (symbol-value reftex-docstruct-symbol))
          (rest (or (member (list 'bof (buffer-file-name)) docstruct)
                    docstruct))
@@ -94,11 +90,11 @@
       (if thebib 'thebib nil))))
 
 (defun reftex-get-bibfile-list ()
-  ;; Return list of bibfiles for current document.
-  ;; When using the chapterbib or bibunits package you should either
-  ;; use the same database files everywhere, or separate parts using
-  ;; different databases into different files (included into the mater file).
-  ;; Then this function will return the applicable database files.
+  "Return list of bibfiles for current document.
+When using the chapterbib or bibunits package you should either
+use the same database files everywhere, or separate parts using
+different databases into different files (included into the mater file).
+Then this function will return the applicable database files."
 
   ;; Ensure access to scanning info
   (reftex-access-scan-info)
@@ -115,16 +111,14 @@
    (cdr (assq 'bib (symbol-value reftex-docstruct-symbol)))
    (error "\\bibliography statement missing or .bib files not found")))
 
-;; Find a certain reference in any of the BibTeX files.
-
+;;; Find a certain reference in any of the BibTeX files.
 (defun reftex-pop-to-bibtex-entry (key file-list &optional mark-to-kill
                                        highlight item return)
-  ;; Find BibTeX KEY in any file in FILE-LIST in another window.
-  ;; If MARK-TO-KILL is non-nil, mark new buffer to kill.
-  ;; If HIGHLIGHT is non-nil, highlight the match.
-  ;; If ITEM in non-nil, search for bibitem instead of database entry.
-  ;; If RETURN is non-nil, just return the entry and restore point.
-
+  "Find BibTeX KEY in any file in FILE-LIST in another window.
+If MARK-TO-KILL is non-nil, mark new buffer to kill.
+If HIGHLIGHT is non-nil, highlight the match.
+If ITEM in non-nil, search for bibitem instead of database entry.
+If RETURN is non-nil, just return the entry and restore point."
   (let* ((re
           (if item
               (concat "\\\\bibitem[ \t]*\\(\\[[^]]*\\]\\)?[ \t]*{"
@@ -178,12 +172,11 @@
           (progn (forward-list 1) (point)))
       (error (min (point-max) (+ 300 (point)))))))
 
-;; Parse bibtex buffers
-
+;;; Parse bibtex buffers
 (defun reftex-extract-bib-entries (buffers)
-  ;; Extract bib entries which match regexps from BUFFERS.
-  ;; BUFFERS is a list of buffers or file names.
-  ;; Return list with entries."
+  "Extract bib entries which match regexps from BUFFERS.
+BUFFERS is a list of buffers or file names.
+Return list with entries."
   (let* (re-list first-re rest-re
                  (buffer-list (if (listp buffers) buffers (list buffers)))
                  found-list entry buffer1 buffer alist
@@ -309,6 +302,8 @@
      (t found-list))))
 
 (defun reftex-bib-sort-author (e1 e2)
+  "Compare bib entries E1 and E2 by author.
+The name of the first different author/editor is used."
   (let ((al1 (reftex-get-bib-names "author" e1))
         (al2 (reftex-get-bib-names "author" e2)))
     (while (and al1 al2 (string= (car al1) (car al2)))
@@ -320,15 +315,17 @@
       (not (stringp (car al1))))))
 
 (defun reftex-bib-sort-year (e1 e2)
+  "Compare bib entries E1 and E2 by year in ascending order."
   (< (string-to-number (or (cdr (assoc "year" e1)) "0"))
      (string-to-number (or (cdr (assoc "year" e2)) "0"))))
 
 (defun reftex-bib-sort-year-reverse (e1 e2)
+  "Compare bib entries E1 and E2 by year in descending order."
   (> (string-to-number (or (cdr (assoc "year" e1)) "0"))
      (string-to-number (or (cdr (assoc "year" e2)) "0"))))
 
 (defun reftex-get-crossref-alist (entry)
-  ;; return the alist from a crossref entry
+  "Return the alist from a crossref ENTRY."
   (let ((crkey (cdr (assoc "crossref" entry)))
         start)
     (save-excursion
@@ -347,10 +344,9 @@
 
 ;; Parse the bibliography environment
 (defun reftex-extract-bib-entries-from-thebibliography (files)
-  ;; Extract bib-entries from the \begin{thebibliography} environment.
-  ;; Parsing is not as good as for the BibTeX database stuff.
-  ;; The environment should be located in file FILE.
-
+  "Extract bib-entries from the \begin{thebibliography} environment.
+Parsing is not as good as for the BibTeX database stuff.
+The environment should be located in FILES."
   (let* (start end buf entries re re-list file default)
     (unless files
       (error "Need file name to find thebibliography environment"))
@@ -430,8 +426,8 @@
     entries))
 
 (defun reftex-get-bibkey-default ()
-  ;; Return the word before the cursor.  If the cursor is in a
-  ;; citation macro, return the word before the macro.
+  "Return the word before the cursor.
+If the cursor is in a citation macro, return the word before the macro."
   (let* ((macro (reftex-what-macro 1)))
     (save-excursion
       (if (and macro (string-match "cite" (car macro)))
@@ -439,10 +435,10 @@
       (skip-chars-backward "^a-zA-Z0-9")
       (reftex-this-word))))
 
-;; Parse and format individual entries
-
+;;; Parse and format individual entries
 (defun reftex-get-bib-names (field entry)
-  ;; Return a list with the author or editor names in ENTRY
+  "Return a list with the author or editor names in ENTRY.
+If FIELD is empty try \"editor\" field."
   (let ((names (reftex-get-bib-field field entry)))
     (if (equal "" names)
         (setq names (reftex-get-bib-field "editor" entry)))
@@ -457,7 +453,9 @@
     (split-string names "\n")))
 
 (defun reftex-parse-bibtex-entry (entry &optional from to raw)
-  ; if RAW is non-nil, keep double quotes/curly braces delimiting fields
+  "Parse BibTeX ENTRY.
+If ENTRY is nil then parse the entry in current buffer between FROM and TO.
+If RAW is non-nil, keep double quotes/curly braces delimiting fields."
   (let (alist key start field)
     (save-excursion
       (save-restriction
@@ -518,7 +516,8 @@
     alist))
 
 (defun reftex-get-bib-field (fieldname entry &optional format)
-  ;; Extract the field FIELDNAME from an ENTRY
+  "Extract the field FIELDNAME from ENTRY.
+If FORMAT is non-nil `format' entry accordingly."
   (let ((cell (assoc fieldname entry)))
     (if cell
         (if format
@@ -527,7 +526,7 @@
       "")))
 
 (defun reftex-format-bib-entry (entry)
-  ;; Format a BibTeX ENTRY so that it is nice to look at
+  "Format a BibTeX ENTRY so that it is nice to look at."
   (let*
       ((auth-list (reftex-get-bib-names "author" entry))
        (authors (mapconcat 'identity auth-list ", "))
@@ -570,7 +569,7 @@
     (concat key "\n     " authors " " year " " extra "\n     " title "\n\n")))
 
 (defun reftex-parse-bibitem (item)
-  ;; Parse a \bibitem entry
+  "Parse a \bibitem entry in ITEM."
   (let ((key "") (text ""))
     (when (string-match "\\`{\\([^}]+\\)}\\([^\000]*\\)" item)
       (setq key (match-string 1 item)
@@ -586,7 +585,7 @@
      (cons "&entry" (concat key " " text)))))
 
 (defun reftex-format-bibitem (item)
-  ;; Format a \bibitem entry so that it is (relatively) nice to look at.
+  "Format a \bibitem entry in ITEM so that it is (relatively) nice to look at."
   (let ((text (reftex-get-bib-field "&text" item))
         (key  (reftex-get-bib-field "&key" item))
         (lines nil))
@@ -603,7 +602,7 @@
       (put-text-property 0 (length text) 'face reftex-bib-author-face text))
     (concat key "\n     " text "\n\n")))
 
-;; Make a citation
+;;; Make a citation
 
 ;;;###autoload
 (defun reftex-citation (&optional no-insert format-key)
@@ -627,7 +626,6 @@ The regular expression uses an expanded syntax: && is interpreted as `and'.
 Thus, `aaaa&&bbb' matches entries which contain both `aaaa' and `bbb'.
 While entering the regexp, completion on knows citation keys is possible.
 `=' is a good regular expression to match all entries in all files."
-
   (interactive)
 
   ;; check for recursive edit
@@ -645,8 +643,7 @@ While entering the regexp, completion on knows citation keys is possible.
     (reftex-kill-temporary-buffers)))
 
 (defun reftex-do-citation (&optional arg no-insert format-key)
-  ;; This really does the work of reftex-citation.
-
+  "This really does the work of `reftex-citation'."
   (let* ((format (reftex-figure-out-cite-format arg no-insert format-key))
          (docstruct-symbol reftex-docstruct-symbol)
          (selected-entries (reftex-offer-bib-menu))
@@ -743,8 +740,8 @@ While entering the regexp, completion on knows citation keys is possible.
     (mapcar 'car selected-entries)))
 
 (defun reftex-figure-out-cite-format (arg &optional no-insert format-key)
-  ;; Check if there is already a cite command at point and change cite format
-  ;; in order to only add another reference in the same cite command.
+  "Check if there is already a cite command at point and change cite format
+in order to only add another reference in the same cite command."
   (let ((macro (car (reftex-what-macro 1)))
         (cite-format-value (reftex-get-cite-format))
         key format)
@@ -802,8 +799,7 @@ While entering the regexp, completion on knows citation keys is possible.
 
 (defvar reftex-select-bib-map)
 (defun reftex-offer-bib-menu ()
-  ;; Offer bib menu and return list of selected items
-
+  "Offer bib menu and return list of selected items."
   (let ((bibtype (reftex-bib-or-thebib))
         found-list rtn key data selected-entries)
     (while
@@ -917,7 +913,7 @@ While entering the regexp, completion on knows citation keys is possible.
     selected-entries))
 
 (defun reftex-restrict-bib-matches (found-list)
-  ;; Limit FOUND-LIST with more regular expressions
+  "Limit FOUND-LIST with more regular expressions."
   (let ((re-list (split-string (read-string
                                 "RegExp [ && RegExp...]: "
                                 nil 'reftex-cite-regexp-hist)
@@ -940,7 +936,7 @@ While entering the regexp, completion on knows citation keys is possible.
       found-list)))
 
 (defun reftex-extract-bib-file (all &optional marked complement)
-  ;; Limit FOUND-LIST with more regular expressions
+  "Limit FOUND-LIST with more regular expressions."
   (let ((file (read-file-name "File to create: ")))
     (find-file-other-window file)
     (if (> (buffer-size) 0)
@@ -963,7 +959,7 @@ While entering the regexp, completion on knows citation keys is possible.
     (goto-char (point-min))))
 
 (defun reftex-insert-bib-matches (list)
-  ;; Insert the bib matches and number them correctly
+  "Insert the bib matches and number them correctly."
   (let ((mouse-face
          (if (memq reftex-highlight-selection '(mouse both))
              reftex-mouse-selected-face
@@ -996,8 +992,7 @@ While entering the regexp, completion on knows citation keys is possible.
        last)))))
 
 (defun reftex-format-citation (entry format)
-  ;; Format a citation from the info in the BibTeX ENTRY
-
+  "Format a citation from the info in the BibTeX ENTRY according to FORMAT."
   (unless (stringp format) (setq format "\\cite{%l}"))
 
   (if (and reftex-comment-citations
@@ -1064,7 +1059,7 @@ While entering the regexp, completion on knows citation keys is possible.
   format)
 
 (defun reftex-make-cite-echo-string (entry docstruct-symbol)
-  ;; Format a bibtex entry for the echo area and cache the result.
+  "Format a bibtex ENTRY for the echo area and cache the result."
   (let* ((key (reftex-get-bib-field "&key" entry))
          (string
           (let* ((reftex-cite-punctuation '(" " " & " " etal.")))
@@ -1088,9 +1083,9 @@ While entering the regexp, completion on knows citation keys is possible.
     string))
 
 (defun reftex-bibtex-selection-callback (data ignore no-revisit)
-  ;; Callback function to be called from the BibTeX selection, in
-  ;; order to display context.  This function is relatively slow and not
-  ;; recommended for follow mode.  It works OK for individual lookups.
+  "Callback function to be called from the BibTeX selection, in
+order to display context.  This function is relatively slow and not
+recommended for follow mode.  It works OK for individual lookups."
   (let ((win (selected-window))
         (key (reftex-get-bib-field "&key" data))
         bibfile-list item bibtype)
@@ -1157,7 +1152,7 @@ While entering the regexp, completion on knows citation keys is possible.
                                               alist))))
 
 (defun reftex-create-bibtex-file (bibfile)
-  "Create a new BibTeX database file with all entries referenced in document.
+  "Create a new BibTeX database BIBFILE with all entries referenced in document.
 The command prompts for a filename and writes the collected
 entries to that file.  Only entries referenced in the current
 document with any \\cite-like macros are used.  The sequence in
@@ -1247,5 +1242,5 @@ created files in the variables `reftex-create-bibtex-header' or
     (message "%d entries extracted and copied to new database"
              (length entries))))
 
-
+(provide 'reftex-cite)
 ;;; reftex-cite.el ends here
diff --git a/lisp/textmodes/reftex-parse.el b/lisp/textmodes/reftex-parse.el
index 3a64aad6a06..a99791e5427 100644
--- a/lisp/textmodes/reftex-parse.el
+++ b/lisp/textmodes/reftex-parse.el
@@ -49,7 +49,8 @@
   (reftex-access-scan-info '(16)))
 
 (defun reftex-do-parse (rescan &optional file)
-  "Do a document rescan.  When allowed, do only a partial scan from FILE."
+  "Do a document rescan.
+When allowed, do only a partial scan from FILE."
 
   ;; Normalize the rescan argument
   (setq rescan (cond ((eq rescan t) t)
@@ -191,7 +192,7 @@ of master file."
 (defvar index-tags)
 
 (defun reftex-parse-from-file (file docstruct master-dir)
-  ;; Scan the buffer for labels and save them in a list.
+  "Scan the buffer for labels and save them in a list."
   (let ((regexp (reftex-everything-regexp))
         (bound 0)
         file-found tmp include-file
@@ -350,8 +351,7 @@ of master file."
     docstruct))
 
 (defun reftex-locate-bibliography-files (master-dir &optional files)
-  ;; Scan buffer for bibliography macro and return file list.
-
+  "Scan buffer for bibliography macro and return file list."
   (unless files
     (save-excursion
       (goto-char (point-min))
@@ -379,10 +379,10 @@ of master file."
     (delq nil files)))
 
 (defun reftex-replace-label-list-segment (old insert &optional entirely)
-  ;; Replace the segment in OLD which corresponds to INSERT.
-  ;; Works with side effects, directly changes old.
-  ;; If entirely is t, just return INSERT.
-  ;; This function also makes sure the old toc markers do not point anywhere.
+  "Replace the segment in OLD which corresponds to INSERT.
+Works with side effects, directly changes old.
+If ENTIRELY is t, just return INSERT.
+This function also makes sure the old toc markers do not point anywhere."
 
   (cond
    (entirely
@@ -404,8 +404,8 @@ of master file."
         new))))
 
 (defun reftex-section-info (file)
-  ;; Return a section entry for the current match.
-  ;; Careful: This function expects the match-data to be still in place!
+  "Return a section entry for the current match.
+Careful: This function expects the match-data to be still in place!"
   (let* ((marker (set-marker (make-marker) (1- (match-beginning 3))))
          (macro (reftex-match-string 3))
          (prefix (save-match-data
@@ -440,9 +440,9 @@ of master file."
           literal (marker-position marker))))
 
 (defun reftex-ensure-index-support (&optional abort)
-  ;; When index support is turned off, ask to turn it on and
-  ;; set the current prefix argument so that `reftex-access-scan-info'
-  ;; will rescan the entire document.
+  "When index support is turned off, ask to turn it on and
+set the current prefix argument so that `reftex-access-scan-info'
+will rescan the entire document."
   (cond
    (reftex-support-index t)
    ((y-or-n-p "Turn on index support and rescan entire document? ")
@@ -460,8 +460,8 @@ of master file."
 
 (defvar test-dummy)
 (defun reftex-index-info (file)
-  ;; Return an index entry for the current match.
-  ;; Careful: This function expects the match-data to be still in place!
+  "Return an index entry for the current match.
+Careful: This function expects the match-data to be still in place!"
   (catch 'exit
     (let* ((macro (reftex-match-string 10))
            (bom (match-beginning 10))
@@ -508,7 +508,7 @@ of master file."
       (list 'index index-tag context file bom arg key showkey sortkey key-end))))
 
 (defun reftex-short-context (env parse &optional bound derive)
-  ;; Get about one line of useful context for the label definition at point.
+  "Get about one line of useful context for the label definition at point."
 
   (if (consp parse)
       (setq parse (if derive (cdr parse) (car parse))))
@@ -568,9 +568,9 @@ of master file."
      "INVALID VALUE OF PARSE"))))
 
 (defun reftex-where-am-I ()
-  ;; Return the docstruct entry above point.  Actually returns a cons
-  ;; cell in which the cdr is a flag indicating if the information is
-  ;; exact (t) or approximate (nil).
+  "Return the docstruct entry above point.
+Actually returns a cons cell in which the cdr is a flag indicating
+if the information is exact (t) or approximate (nil)."
 
   (let ((docstruct (symbol-value reftex-docstruct-symbol))
         (cnt 0) rtn rtn-if-no-other
@@ -748,10 +748,10 @@ of master file."
   )
 
 (defsubst reftex-move-to-previous-arg (&optional bound)
-  ;; Assuming that we are in front of a macro argument,
-  ;; move backward to the closing parenthesis of the previous argument.
-  ;; This function understands the splitting of macros over several lines
-  ;; in TeX.
+  "Assuming that we are in front of a macro argument,
+move backward to the closing parenthesis of the previous argument.
+This function understands the splitting of macros over several lines
+in TeX."
   (cond
    ;; Just to be quick:
    ((memq (preceding-char) '(?\] ?\})))
@@ -764,28 +764,27 @@ of master file."
    (t nil)))
 
 (defun reftex-what-macro-safe (which &optional bound)
-  ;; reftex-what-macro with special syntax table.
+  "Call `reftex-what-macro' with special syntax table."
   (reftex-with-special-syntax
    (reftex-what-macro which bound)))
 
 (defun reftex-what-macro (which &optional bound)
-  ;; Find out if point is within the arguments of any TeX-macro.
-  ;; The return value is either ("\\macro" . (point)) or a list of them.
-
-  ;; If WHICH is nil, immediately return nil.
-  ;; If WHICH is 1, return innermost enclosing macro.
-  ;; If WHICH is t, return list of all macros enclosing point.
-  ;; If WHICH is a list of macros, look only for those macros and return the
-  ;;    name of the first macro in this list found to enclose point.
-  ;; If the optional BOUND is an integer, bound backwards directed
-  ;;    searches to this point.  If it is nil, limit to nearest \section -
-  ;;    like statement.
-
-  ;; This function is pretty stable, but can be fooled if the text contains
-  ;; things like \macro{aa}{bb} where \macro is defined to take only one
-  ;; argument.  As RefTeX cannot know this, the string "bb" would still be
-  ;; considered an argument of macro \macro.
-
+  "Find out if point is within the arguments of any TeX-macro.
+The return value is either (\"\\macro\" . (point)) or a list of them.
+
+If WHICH is nil, immediately return nil.
+If WHICH is 1, return innermost enclosing macro.
+If WHICH is t, return list of all macros enclosing point.
+If WHICH is a list of macros, look only for those macros and return the
+  name of the first macro in this list found to enclose point.
+If the optional BOUND is an integer, bound backwards directed
+  searches to this point.  If it is nil, limit to nearest \\section -
+  like statement.
+
+This function is pretty stable, but can be fooled if the text contains
+things like \\macro{aa}{bb} where \\macro is defined to take only one
+argument.  As RefTeX cannot know this, the string \"bb\" would still be
+considered an argument of macro \\macro."
   (unless reftex-section-regexp (reftex-compile-variables))
   (catch 'exit
     (if (null which) (throw 'exit nil))
@@ -832,20 +831,19 @@ of master file."
         (nreverse cmd-list)))))
 
 (defun reftex-what-environment (which &optional bound)
-  ;; Find out if point is inside a LaTeX environment.
-  ;; The return value is (e.g.) either ("equation" . (point)) or a list of
-  ;; them.
-
-  ;; If WHICH is nil, immediately return nil.
-  ;; If WHICH is 1, return innermost enclosing environment.
-  ;; If WHICH is t, return list of all environments enclosing point.
-  ;; If WHICH is a list of environments, look only for those environments and
-  ;;   return the name of the first environment in this list found to enclose
-  ;;   point.
-
-  ;; If the optional BOUND is an integer, bound backwards directed searches to
-  ;; this point.  If it is nil, limit to nearest \section - like statement.
-
+  "Find out if point is inside a LaTeX environment.
+The return value is (e.g.) either (\"equation\" . (point)) or a list of
+them.
+
+If WHICH is nil, immediately return nil.
+If WHICH is 1, return innermost enclosing environment.
+If WHICH is t, return list of all environments enclosing point.
+If WHICH is a list of environments, look only for those environments and
+  return the name of the first environment in this list found to enclose
+  point.
+
+If the optional BOUND is an integer, bound backwards directed searches to
+this point.  If it is nil, limit to nearest \\section - like statement."
   (unless reftex-section-regexp (reftex-compile-variables))
   (catch 'exit
     (save-excursion
@@ -870,18 +868,17 @@ of master file."
         (nreverse env-list)))))
 
 (defun reftex-what-special-env (which &optional bound)
-  ;; Run the special environment parsers and return the matches.
-  ;;
-  ;; The return value is (e.g.) either ("my-parser-function" . (point))
-  ;; or a list of them.
-
-  ;; If WHICH is nil, immediately return nil.
-  ;; If WHICH is 1, return innermost enclosing environment.
-  ;; If WHICH is t, return list of all environments enclosing point.
-  ;; If WHICH is a list of environments, look only for those environments and
-  ;;   return the name of the first environment in this list found to enclose
-  ;;   point.
+  "Run the special environment parsers and return the matches.
+
+The return value is (e.g.) either (\"my-parser-function\" . (point))
+or a list of them.
 
+If WHICH is nil, immediately return nil.
+If WHICH is 1, return innermost enclosing environment.
+If WHICH is t, return list of all environments enclosing point.
+If WHICH is a list of environments, look only for those environments and
+  return the name of the first environment in this list found to enclose
+  point."
   (unless reftex-section-regexp (reftex-compile-variables))
   (catch 'exit
     (save-excursion
@@ -911,10 +908,10 @@ of master file."
           (car specials))))))
 
 (defsubst reftex-move-to-next-arg (&optional ignore)
-  ;; Assuming that we are at the end of a macro name or a macro argument,
-  ;; move forward to the opening parenthesis of the next argument.
-  ;; This function understands the splitting of macros over several lines
-  ;; in TeX.
+  "Assuming that we are at the end of a macro name or a macro argument,
+move forward to the opening parenthesis of the next argument.
+This function understands the splitting of macros over several lines
+in TeX."
   (cond
    ;; Just to be quick:
    ((memq (following-char) '(?\[ ?\{)))
@@ -930,8 +927,8 @@ of master file."
     (reftex-nth-arg (nth 5 entry) (nth 6 entry))))
 
 (defun reftex-nth-arg (n &optional opt-args)
-  ;; Return the nth following {} or [] parentheses content.
-  ;; OPT-ARGS is a list of argument numbers which are optional.
+  "Return the Nth following {} or [] parentheses content.
+OPT-ARGS is a list of argument numbers which are optional."
 
   ;; If we are sitting at a macro start, skip to end of macro name.
   (and (eq (following-char) ?\\) (skip-chars-forward "a-zA-Z*\\\\"))
@@ -974,8 +971,8 @@ of master file."
     (error nil)))
 
 (defun reftex-context-substring (&optional to-end)
-  ;; Return up to 150 chars from point
-  ;; When point is just after a { or [, limit string to matching parenthesis
+  "Return up to 150 chars from point.
+When point is just after a { or [, limit string to matching parenthesis"
   (cond
    (to-end
     ;; Environment - find next \end
@@ -1007,8 +1004,7 @@ of master file."
 (defvar reftex-section-numbers (make-vector reftex-max-section-depth 0))
 
 (defun reftex-init-section-numbers (&optional toc-entry appendix)
-  ;; Initialize the section numbers with zeros or with what is found
-  ;; in the toc entry.
+  "Initialize the section numbers with zeros or with what is found in the TOC-ENTRY."
   (let* ((level  (or (nth 5 toc-entry) -1))
          (numbers (nreverse (split-string (or (nth 6 toc-entry) "") "\\.")))
          (depth (1- (length reftex-section-numbers)))
@@ -1026,8 +1022,8 @@ of master file."
   (put 'reftex-section-numbers 'appendix appendix))
 
 (defun reftex-section-number (&optional level star)
-  ;; Return a string with the current section number.
-  ;; When LEVEL is non-nil, increase section numbers on that level.
+  "Return a string with the current section number.
+When LEVEL is non-nil, increase section numbers on that level."
   (let* ((depth (1- (length reftex-section-numbers))) idx n (string "")
          (appendix (get 'reftex-section-numbers 'appendix))
          (partspecial (and (not reftex-part-resets-chapter)
@@ -1073,7 +1069,7 @@ of master file."
         string))))
 
 (defun reftex-roman-number (n)
-  ;; Return as a string the roman number equal to N.
+  "Return as a string the roman number equal to N."
   (let ((nrest n)
         (string "")
         (list '((1000 . "M") ( 900 . "CM") ( 500 . "D") ( 400 . "CD")