Subject: [PATCH] - checkdoc fixes for reftex.el

From: Jeremy Bryant <[email-masked]>
Date: Thu, 17 Apr 2025 12:51:31 +0100

These checkdoc fixes are mostly converting comments to docstrings for defuns.  A
couple of capitalizations.
This helps with readablility and Emacs Lisp conventions.

Any further checkdoc changes to the docstrings could be separate
patches, such as more systematically capitalizations of args.

Feedback welcome.

>From 47d884899c61cfe17754a5c4acd7ea7391b3ed58 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <[email-masked]>
Date: Mon, 7 Apr 2025 21:31:46 +0100
Subject: [PATCH] * lisp/textmodes/reftex.el: checkdoc fixes, comments to
 docstrings

Convert comment to docstring in functions
(reftex-next-multifile-index)
(reftex-TeX-master-file)
(reftex-is-multi)
(reftex-get-cite-format)
(reftex-ensure-compiled-variables)
(reftex-erase-all-selection-and-index-buffers)
(reftex-compile-variables)
(reftex-parse-args)
(reftex-access-scan-info)
(reftex-check-parse-consistency)
(reftex-select-external-document)
(reftex-find-file-externally)
(reftex-access-search-path)
(reftex-find-file-on-path)
(reftex-parse-colon-path)
(reftex-expand-path)
(reftex-recursive-directory-list)
(reftex-typekey-check)
(reftex-check-recursive-edit)
(reftex-no-props)
(reftex-match-string)
(reftex-kill-buffer)
(reftex-erase-buffer)
(reftex-this-word)
(reftex-all-assq)
(reftex-all-assoc-string)
(reftex-last-assoc-before-elt)
(reftex-sublist-nth)
(reftex-make-selection-buffer-name)
(reftex-make-index-buffer-name)
(reftex-truncate)
(reftex-nearest-match)
(reftex-auto-mode-alist)
(reftex-enlarge-to-fit)
(reftex-select-with-char)
(reftex-make-regexp-allow-for-ctrl-m)
(reftex-visited-files)
(reftex-get-file-buffer-force)
(reftex-kill-temporary-buffers)
(reftex-splice-symbols-into-list)
(reftex-uniquify)
(reftex-uniquify-by-car)
(reftex-nicify-text)
(reftex-refontify)
(reftex-fontify-select-label-buffer)
(reftex-select-font-lock-fontify-region)
(reftex-verified-face)
(reftex-highlight-shall-die)

Convert comment to docstring and capitalize argument
(reftex-silence-toc-markers)

Capitalise argument
(reftex-set-cite-format)
---
 lisp/textmodes/reftex.el | 205 ++++++++++++++++++++-------------------
 1 file changed, 103 insertions(+), 102 deletions(-)

diff --git a/lisp/textmodes/reftex.el b/lisp/textmodes/reftex.el
index fda506a6d87..e51e03ca350 100644
--- a/lisp/textmodes/reftex.el
+++ b/lisp/textmodes/reftex.el
@@ -276,7 +276,7 @@ reftex-multifile-index
 (defvar-local reftex-docstruct-symbol nil)
 
 (defun reftex-next-multifile-index ()
-  ;; Return the next free index for multifile symbols.
+  "Return the next free index for multifile symbols."
   (incf reftex-multifile-index))
 
 (defun reftex-tie-multifile-symbols ()
@@ -322,10 +322,10 @@ reftex-untie-multifile-symbols
       (set symbol nil))))
 
 (defun reftex-TeX-master-file ()
-  ;; Return the name of the master file associated with the current buffer.
-  ;; When AUCTeX is loaded, we will use it's more sophisticated method.
-  ;; We also support the default TeX and LaTeX modes by checking for a
-  ;; variable tex-main-file.
+  "Return the name of the master file associated with the current buffer.
+When AUCTeX is loaded, we will use it's more sophisticated method.
+We also support the default TeX and LaTeX modes by checking for a
+variable `tex-main-file'."
   (let
       ((master
         (cond
@@ -392,14 +392,14 @@ reftex-TeX-master-file
     (expand-file-name master)))
 
 (defun reftex-is-multi ()
-  ;; Tell if this is a multifile document.  When not sure, say yes.
+  "Tell if this is a multifile document.  When not sure, say yes."
   (let ((entry (assq 'is-multi (symbol-value reftex-docstruct-symbol))))
     (if entry
         (nth 1 entry)
       t)))
 
 (defun reftex-set-cite-format (value)
-  "Set the document-local value of `reftex-cite-format'.
+  "Set the document-local VALUE of `reftex-cite-format'.
 When such a value exists, it overwrites the setting given with
 `reftex-cite-format'.  See the documentation of `reftex-cite-format'
 for possible values.  This function should be used from AUCTeX style files."
@@ -410,8 +410,9 @@ reftex-set-cite-format
     (put reftex-docstruct-symbol 'reftex-cite-format value)))
 
 (defun reftex-get-cite-format ()
-  ;; Return the current citation format.  Either the document-local value in
-  ;; reftex-cite-format-symbol, or the global value in reftex-cite-format.
+  "Return the current citation format.
+Either the document-local value in
+reftex-cite-format-symbol, or the global value in reftex-cite-format."
   (if (and reftex-docstruct-symbol
            (symbolp reftex-docstruct-symbol)
            (get reftex-docstruct-symbol 'reftex-cite-format))
@@ -644,7 +645,7 @@ reftex-cache-variables
 ))
 
 (defun reftex-ensure-compiled-variables ()
-  ;; Recompile the label alist when necessary
+  "Recompile the label alist when necessary."
   (let* ((mem reftex-memory)
          (cache (get reftex-docstruct-symbol 'reftex-cache))
          (cmem  (car cache))
@@ -724,7 +725,7 @@ reftex-reset-scanning-information
           (set (symbol-value symbol) nil)))))
 
 (defun reftex-erase-all-selection-and-index-buffers ()
-  ;; Remove all selection buffers associated with current document.
+  "Remove all selection buffers associated with current document."
   (mapc
    (lambda (type)
      (reftex-erase-buffer (reftex-make-selection-buffer-name type)))
@@ -736,7 +737,7 @@ reftex-erase-all-selection-and-index-buffers
    (cdr (assoc 'index-tags (symbol-value reftex-docstruct-symbol)))))
 
 (defun reftex-compile-variables ()
-  ;; Compile the information in reftex-label-alist & Co.
+  "Compile the information in reftex-label-alist & Co."
 
   (message "Compiling label environment definitions...")
 
@@ -1076,8 +1077,8 @@ reftex-compile-variables
        (mapcar #'symbol-value reftex-cache-variables)))
 
 (defun reftex-parse-args (macro)
-  ;; Return a list of macro name, nargs, arg-nr which is label and a list of
-  ;; optional argument indices.
+  "Return a list of macro name, nargs, arg-nr which is label and a list of
+optional argument indices."
   (if (string-match "[[{]\\*?[]}]" macro)
       (progn
         (let ((must-match (substring macro 0 (match-beginning 0)))
@@ -1099,12 +1100,11 @@ reftex-parse-args
 ;;; Accessing the parse information
 
 (defun reftex-access-scan-info (&optional rescan file)
-  "Ensure access to the scanning info for the current file."
-  ;; When the multifile symbols are not yet tied,
-  ;; tie them.  When they are empty or RESCAN is non-nil, scan the document.
-  ;; But, when RESCAN is -1, don't rescan even if docstruct is empty.
-  ;; When FILE is non-nil, parse only from that file.
-
+  "Ensure access to the scanning info for the current file.
+When the multifile symbols are not yet tied, tie them.
+When they are empty or RESCAN is non-nil, scan the document.
+But, when RESCAN is -1, don't rescan even if docstruct is empty.
+When FILE is non-nil, parse only from that file."
   ;; Error out in a buffer without a file.
   (if (and reftex-mode
 	   (not (buffer-file-name)))
@@ -1148,7 +1148,7 @@ reftex-scanning-info-available-p
        t))
 
 (defun reftex-silence-toc-markers (list n)
-  ;; Set all toc markers in the first N entries in list to nil
+  "Set all toc markers in the first N entries in LIST to nil."
   (while (and list (> (decf n) -1))
     (and (eq (car (car list)) 'toc)
          (markerp (nth 4 (car list)))
@@ -1234,7 +1234,7 @@ reftex-access-parse-file
       t))))
 
 (defun reftex-check-parse-consistency ()
-  ;; Check if parse file is consistent, throw an error if not.
+  "Check if parse file is consistent, throw an error if not."
 
   ;; Check if the master is the same: when moving a document, this will see it.
   (let* ((real-master (reftex-TeX-master-file))
@@ -1256,7 +1256,7 @@ reftex-check-parse-consistency
   )
 
 (defun reftex-select-external-document (xr-alist xr-index)
-  ;; Return index of an external document.
+  "Return index of an external document."
   (let* ((len (length xr-alist)) (highest (1- (+ ?0 len)))
          (prompt (format "[%c-%c] Select    TAB: Read prefix with completion"
                          ?0 highest))
@@ -1338,9 +1338,9 @@ reftex-locate-file
           (t (message "No such file: %s (ignored)" file) nil))))
 
 (defun reftex-find-file-externally (file type &optional master-dir)
-  ;; Use external program to find FILE.
-  ;; The program is taken from `reftex-external-file-finders'.
-  ;; Interpret relative path definitions starting from MASTER-DIR.
+  "Use external program to find FILE.
+The program is taken from `reftex-external-file-finders'.
+Interpret relative path definitions starting from MASTER-DIR."
   (let ((default-directory (or master-dir default-directory))
         (prg (cdr (assoc type reftex-external-file-finders)))
         out)
@@ -1362,13 +1362,13 @@ reftex-process-string
           (apply #'call-process program nil '(t nil) nil args))))))
 
 (defun reftex-access-search-path (type &optional recurse master-dir file)
-  ;; Access path from environment variables.  TYPE is either "tex" or "bib".
-  ;; When RECURSE is t, expand path elements ending in `//' recursively.
-  ;; Relative path elements are left as they are.  However, relative recursive
-  ;; elements are expanded with MASTER-DIR as default directory.
-  ;; The expanded path is cached for the next search.
-  ;; FILE is just for the progress message.
-  ;; Returns the derived path.
+  "Access path from environment variables.  TYPE is either \"tex\" or \"bib\".
+When RECURSE is t, expand path elements ending in `//' recursively.
+Relative path elements are left as they are.  However, relative recursive
+elements are expanded with MASTER-DIR as default directory.
+The expanded path is cached for the next search.
+FILE is just for the progress message.
+Returns the derived path."
   (let* ((pathvar (intern (concat "reftex-" type "-path"))))
     (when (null (get pathvar 'status))
       ;; Get basic path
@@ -1422,8 +1422,8 @@ reftex-access-search-path
       (symbol-value pathvar))))
 
 (defun reftex-find-file-on-path (file path &optional def-dir)
-  ;; Find FILE along the directory list PATH.
-  ;; DEF-DIR is the default directory for expanding relative path elements.
+  "Find FILE along the directory list PATH.
+DEF-DIR is the default directory for expanding relative path elements."
   (catch 'exit
     (when (file-name-absolute-p file)
       (if (file-regular-p file)
@@ -1440,8 +1440,8 @@ reftex-find-file-on-path
       nil)))
 
 (defun reftex-parse-colon-path (path)
-  ;; Like parse-colon-parse, but // or /~ are left alone.
-  ;; Trailing ! or !! will be converted into `//' (emTeX convention)
+  "Like parse-colon-parse, but // or /~ are left alone.
+Trailing ! or !! will be converted into `//' (emTeX convention)"
   (mapcar
    (lambda (dir)
      (if (string-match "\\(//+\\|/*!+\\)\\'" dir)
@@ -1450,8 +1450,8 @@ reftex-parse-colon-path
    (delete "" (split-string path (concat path-separator "+")))))
 
 (defun reftex-expand-path (path &optional default-dir)
-  ;; Expand parts of path ending in `//' recursively into directory list.
-  ;; Relative recursive path elements are expanded relative to DEFAULT-DIR.
+  "Expand parts of path ending in `//' recursively into directory list.
+Relative recursive path elements are expanded relative to DEFAULT-DIR."
   (let (path1 dir recursive)
     (while (setq dir (pop path))
       (if (setq recursive (string= (substring dir -2) "//"))
@@ -1467,7 +1467,7 @@ reftex-expand-path
     (nreverse path1)))
 
 (defun reftex-recursive-directory-list (dir)
-  ;; Return a list of all directories below DIR, including DIR itself
+  "Return a list of all directories below DIR, including DIR itself."
   (let ((path (list dir)) path1 file files)
     (while (setq dir (pop path))
       (when (file-directory-p dir)
@@ -1483,7 +1483,7 @@ reftex-recursive-directory-list
 ;;; Some generally useful functions
 
 (defun reftex-typekey-check (typekey conf-variable &optional n)
-  ;; Check if CONF-VARIABLE is true or contains TYPEKEY
+  "Check if CONF-VARIABLE is true or contains TYPEKEY."
   (and n (setq conf-variable (nth n conf-variable)))
   (or (eq conf-variable t)
       (and (stringp conf-variable)
@@ -1491,8 +1491,8 @@ reftex-typekey-check
              (string-match (concat "[" conf-variable "]") typekey)))))
 
 (defun reftex-check-recursive-edit ()
-  ;; Check if we are already in a recursive edit.  Abort with helpful
-  ;; message if so.
+  "Check if we are already in a recursive edit.
+Abort with helpful message if so."
   (if (marker-position reftex-recursive-edit-marker)
       (error
        (substitute-command-keys
@@ -1513,26 +1513,26 @@ reftex-in-comment
 	 pos t)))))
 
 (defun reftex-no-props (string)
-  ;; Return STRING with all text properties removed
+  "Return STRING with all text properties removed."
   (and (stringp string)
        (set-text-properties 0 (length string) nil string))
   string)
 
 (defun reftex-match-string (n)
-  ;; Match string without properties
+  "Match string without properties."
   (when (match-beginning n)
     (buffer-substring-no-properties (match-beginning n) (match-end n))))
 
 (define-obsolete-function-alias 'reftex-region-active-p #'use-region-p "28.1")
 
 (defun reftex-kill-buffer (buffer)
-  ;; Kill buffer if it exists.
+  "Kill BUFFER if it exists."
   (and (setq buffer (get-buffer buffer))
        (kill-buffer buffer)))
 
 (defun reftex-erase-buffer (&optional buffer)
-  ;; Erase BUFFER if it exists.  BUFFER defaults to current buffer.
-  ;; This even erases read-only buffers.
+  "Erase BUFFER if it exists.  BUFFER defaults to current buffer.
+This even erases read-only buffers."
   (cond
    ((null buffer)
     ;; erase current buffer
@@ -1543,7 +1543,7 @@ reftex-erase-buffer
       (let ((inhibit-read-only t)) (erase-buffer))))))
 
 (defun reftex-this-word (&optional class)
-  ;; Grab the word around point.
+  "Grab the word around point."
   (setq class (or class "-a-zA-Z0-9:_/.*;|"))
   (save-excursion
     (buffer-substring-no-properties
@@ -1556,7 +1556,7 @@ reftex-number
     ""))
 
 (defun reftex-all-assq (key list)
-  ;; Return a list of all associations of KEY in LIST.  Comparison with eq.
+  "Return a list of all associations of KEY in LIST.  Comparison with eq."
   (let (rtn)
     (while (setq list (memq (assq key list) list))
       (push (car list) rtn)
@@ -1564,7 +1564,7 @@ reftex-all-assq
     (nreverse rtn)))
 
 (defun reftex-all-assoc-string (key list)
-  ;; Return a list of all associations of KEY in LIST.  Comparison with string=.
+  "Return a list of all associations of KEY in LIST.  Comparison with string=."
   (let (rtn)
     (while list
       (if (string= (car (car list)) key)
@@ -1573,11 +1573,11 @@ reftex-all-assoc-string
     (nreverse rtn)))
 
 (defun reftex-last-assoc-before-elt (key elt list &optional exclusive)
-  ;; Find the last association of KEY in LIST before or at ELT
-  ;; ELT is found in LIST with equal, not eq.
-  ;; Returns nil when either KEY or elt are not found in LIST.
-  ;; When EXCLUSIVE is non-nil, ELT cannot be the return value.
-  ;; On success, returns the association.
+  "Find the last association of KEY in LIST before or at ELT
+ELT is found in LIST with equal, not eq.
+Returns nil when either KEY or elt are not found in LIST.
+When EXCLUSIVE is non-nil, ELT cannot be the return value.
+On success, returns the association."
   (let* ((elt (car (member elt list))) (ex (not exclusive)) ass last-ass)
     (while (and (setq ass (assoc key list))
                 (setq list (memq ass list))
@@ -1588,10 +1588,10 @@ reftex-last-assoc-before-elt
     last-ass))
 
 (defun reftex-sublist-nth (list nth predicate &optional completion)
-  ;; Make a list of the NTH elements of all members of LIST which
-  ;; fulfill PREDICATE.
-  ;; When COMPLETION is non-nil, make all elements of the resulting
-  ;; list also a list, so that the result can be used for completion.
+  "Make a list of the NTH elements of all members of LIST which
+fulfill PREDICATE.
+When COMPLETION is non-nil, make all elements of the resulting
+list also a list, so that the result can be used for completion."
   (let (rtn)
     (while list
       (if (funcall predicate (car list))
@@ -1603,20 +1603,20 @@ reftex-sublist-nth
     (nreverse rtn)))
 
 (defun reftex-make-selection-buffer-name (type &optional index)
-  ;; Make unique name for a selection buffer.
+  "Make unique name for a selection buffer."
   (format " *RefTeX[%s][%d]*"
           type (or index (get reftex-docstruct-symbol :master-index) 0)))
 
 (defun reftex-make-index-buffer-name (tag &optional cnt)
-  ;; Make unique name for an index buffer.
+  "Make unique name for an index buffer."
   (format "*Index[%s][%d]*"
           tag (or cnt (get reftex-docstruct-symbol :master-index) 0)))
 
 (defun reftex-truncate (string ncols &optional ellipses padding)
-  ;; Truncate STRING to NCOLS characters.
-  ;; When PADDING is non-nil, and string is shorter than NCOLS, fill with
-  ;; white space to NCOLS characters.  When ELLIPSES is non-nil and the
-  ;; string needs to be truncated, replace last 3 characters by dots.
+  "Truncate STRING to NCOLS characters.
+When PADDING is non-nil, and string is shorter than NCOLS, fill with
+white space to NCOLS characters.  When ELLIPSES is non-nil and the
+string needs to be truncated, replace last 3 characters by dots."
   (setq string
         (if (<= (length string) ncols)
             string
@@ -1628,9 +1628,9 @@ reftex-truncate
     string))
 
 (defun reftex-nearest-match (regexp &optional max-length)
-  ;; Find the nearest match of REGEXP.  Set the match data.
-  ;; If POS is given, calculate distances relative to it.
-  ;; Return nil if there is no match.
+  "Find the nearest match of REGEXP.  Set the match data.
+If POS is given, calculate distances relative to it.
+Return nil if there is no match."
   (let ((pos (point))
         (dist (or max-length (length regexp)))
         match1 match2 match)
@@ -1650,8 +1650,8 @@ reftex-nearest-match
     (if match (progn (set-match-data match) t) nil)))
 
 (defun reftex-auto-mode-alist ()
-  ;; Return an `auto-mode-alist' with only the .gz (etc) thingies.
-  ;; Stolen from gnus nnheader.
+  "Return an `auto-mode-alist' with only the .gz (etc) thingies.
+Stolen from gnus nnheader."
   (let ((alist auto-mode-alist)
         out)
     (while alist
@@ -1661,8 +1661,8 @@ reftex-auto-mode-alist
     (nreverse out)))
 
 (defun reftex-enlarge-to-fit (buf2 &optional keep-current)
-  ;; Enlarge other window displaying buffer to show whole buffer if possible.
-  ;; If KEEP-CURRENT in non-nil, current buffer must remain visible.
+  "Enlarge other window displaying buffer to show whole buffer if possible.
+If KEEP-CURRENT in non-nil, current buffer must remain visible."
   (let* ((win1 (selected-window))
          (buf1 (current-buffer))
          (win2 (get-buffer-window buf2))) ;; Only on current frame.
@@ -1680,9 +1680,9 @@ reftex-enlarge-to-fit
       (shrink-window (- (window-height) window-min-height))))))
 
 (defun reftex-select-with-char (prompt help-string &optional delay-time scroll)
-  ;; Offer to select something with PROMPT and, after DELAY-TIME seconds,
-  ;; also with HELP-STRING.
-  ;; When SCROLL is non-nil, use SPC and DEL to scroll help window.
+  "Offer to select something with PROMPT and, after DELAY-TIME seconds,
+also with HELP-STRING.
+When SCROLL is non-nil, use SPC and DEL to scroll help window."
   (let ((char ?\?))
     (save-window-excursion
       (catch 'exit
@@ -1720,7 +1720,7 @@ reftex-select-with-char

 (defun reftex-make-regexp-allow-for-ctrl-m (string)
-  ;; convert STRING into a regexp, allowing ^M for \n and vice versa
+  "Convert STRING into a regexp, allowing ^M for \n and vice versa."
   (let ((start -2))
     (setq string (regexp-quote string))
     (while (setq start (string-match "[\n\r]" string (+ 3 start)))
@@ -1731,16 +1731,16 @@ 'reftex-get-buffer-visiting
   #'find-buffer-visiting "28.1")
 
 (defun reftex-visited-files (list)
-  ;; Takes a list of filenames and returns the buffers of those already visited
+  "Takes a LIST of filenames and return the buffers of those already visited."
   (delq nil (mapcar (lambda (x) (if (find-buffer-visiting x) x nil))
                     list)))
 
 (defun reftex-get-file-buffer-force (file &optional mark-to-kill)
-  ;; Return a buffer visiting file.  Make one, if necessary.
-  ;; If neither such a buffer nor the file exist, return nil.
-  ;; If MARK-TO-KILL is t and there is no live buffer, visit the file with
-  ;; initializations according to `reftex-initialize-temporary-buffers',
-  ;; and mark the buffer to be killed after use.
+  "Return a buffer visiting FILE.  Make one, if necessary.
+If neither such a buffer nor the file exist, return nil.
+If MARK-TO-KILL is t and there is no live buffer, visit the file with
+initializations according to `reftex-initialize-temporary-buffers',
+and mark the buffer to be killed after use."
 
   (let ((buf (find-buffer-visiting file)))
 
@@ -1784,7 +1784,7 @@ reftex-get-file-buffer-force
           (t nil))))
 
 (defun reftex-kill-temporary-buffers (&optional buffer)
-  ;; Kill all buffers in the list reftex-kill-temporary-buffers.
+  "Kill all buffers in the list reftex-kill-temporary-buffers."
   (cond
    (buffer
     (when (member buffer reftex-buffers-to-kill)
@@ -1803,8 +1803,8 @@ reftex-kill-temporary-buffers
       (pop reftex-buffers-to-kill)))))
 
 (defun reftex-splice-symbols-into-list (list alist)
-  ;; Splice the association in ALIST of any symbols in LIST into the list.
-  ;; Return new list.
+  "Splice the association in ALIST of any symbols in LIST into the list.
+Return new list."
   (let (rtn tmp)
     (while list
       (while (and (not (null (car list)))  ;; keep list elements nil
@@ -1820,8 +1820,8 @@ reftex-splice-symbols-into-list
     (nreverse rtn)))
 
 (defun reftex-uniquify (list &optional sort)
-  ;; Return a list of all strings in LIST, but each only once, keeping order
-  ;; unless SORT is set (faster!).
+  "Return a list of all strings in LIST, but each only once, keeping order
+unless SORT is set (faster!)."
   (setq list (copy-sequence list))
   (if sort
       (progn
@@ -1852,9 +1852,9 @@ reftex-uniquify
     (delq nil list)))
 
 (defun reftex-uniquify-by-car (alist &optional keep-list sort)
-  ;; Return a list of all elements in ALIST, but each car only once.
-  ;; Elements of KEEP-LIST are not removed even if duplicate.
-  ;; The order is kept unless SORT is set (faster!).
+  "Return a list of all elements in ALIST, but each car only once.
+Elements of KEEP-LIST are not removed even if duplicate.
+The order is kept unless SORT is set (faster!)."
   (setq keep-list (sort (copy-sequence keep-list) #'string<)
 	alist (copy-sequence alist))
   (if sort
@@ -1990,8 +1990,8 @@ reftex-convert-string
     string))
 
 (defun reftex-nicify-text (text)
-  ;; Make TEXT nice for inclusion as context into label menu.
-  ;; 1. remove line breaks and extra white space
+  "Make TEXT nice for inclusion as context into label menu.
+1. remove line breaks and extra white space"
   (while (string-match "[\n\r\t]\\|[ \t][ \t]+" text)
     (setq text (replace-match " " nil t text)))
   ;; 2. cut before the next `\end{' or `\item' or `\\'
@@ -2015,7 +2015,7 @@ reftex-nicify-text
 ;;; Fontification and Highlighting
 
 (defun reftex-refontify ()
-  ;; Return t if we need to refontify context
+  "Return t if we need to refontify context."
   (and reftex-use-fonts
        (or (eq t reftex-refontify-context)
            (and (eq 1 reftex-refontify-context)
@@ -2023,8 +2023,9 @@ reftex-refontify
                 (and (featurep 'x-symbol-tex) (not (boundp 'x-symbol-mode)))))))
 
 (defun reftex-fontify-select-label-buffer (parent-buffer)
-  ;; Fontify the `*RefTeX Select*' buffer.  Buffer is temporarily renamed to
-  ;; start with none-SPC char, because Font-Lock otherwise refuses operation.
+  "Fontify the `*RefTeX Select*' buffer.
+Buffer is temporarily renamed to
+start with none-SPC char, because Font-Lock otherwise refuses operation."
   (run-hook-with-args 'reftex-pre-refontification-functions
                       parent-buffer 'reftex-ref)
   (let* ((oldname (buffer-name))
@@ -2042,7 +2043,7 @@ reftex-fontify-select-label-buffer
       (rename-buffer oldname))))
 
 (defun reftex-select-font-lock-fontify-region (beg end &optional _loudly)
-  ;; Fontify a region, but only lines starting with a dot.
+  "Fontify a region, but only lines starting with a dot."
   (let ((func (if (fboundp 'font-lock-default-fontify-region)
                   'font-lock-default-fontify-region
                 'font-lock-fontify-region))
@@ -2056,10 +2057,10 @@ reftex-select-font-lock-fontify-region
 (defun reftex-select-font-lock-unfontify (&rest _ignore) t)
 
 (defun reftex-verified-face (&rest faces)
-  ;; Return the first valid face in FACES, or nil if none is valid.
-  ;; Also, when finding a nil element in FACES, return nil.  This
-  ;; function is just a safety net to catch name changes of builtin
-  ;; fonts. Currently it is only used for reftex-label-face.
+  "Return the first valid face in FACES, or nil if none is valid.
+Also, when finding a nil element in FACES, return nil.  This
+function is just a safety net to catch name changes of builtin
+fonts.  Currently it is only used for reftex-label-face."
   (let (face)
     (catch 'exit
       (while (setq face (pop faces))
@@ -2094,7 +2095,7 @@ reftex-unhighlight
   (delete-overlay (aref reftex-highlight-overlays index)))
 
 (defun reftex-highlight-shall-die ()
-  ;; Function used in pre-command-hook to remove highlights.
+  "Function used in pre-command-hook to remove highlights."
   (remove-hook 'pre-command-hook #'reftex-highlight-shall-die)
   (reftex-unhighlight 0))
 
-- 
2.47.2