From unknown Sat Jun 14 19:33:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#77864: [PATCH] - checkdoc fixes for reftex.el Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-auctex@gnu.org Resent-Date: Thu, 17 Apr 2025 11:53:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 77864 X-GNU-PR-Package: auctex X-GNU-PR-Keywords: patch To: 77864@debbugs.gnu.org X-Debbugs-Original-To: bug-auctex@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.174489073219962 (code B ref -1); Thu, 17 Apr 2025 11:53:02 +0000 Received: (at submit) by debbugs.gnu.org; 17 Apr 2025 11:52:12 +0000 Received: from localhost ([127.0.0.1]:46064 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1u5Nms-0005Bs-W8 for submit@debbugs.gnu.org; Thu, 17 Apr 2025 07:52:12 -0400 Received: from lists.gnu.org ([2001:470:142::17]:36066) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1u5Nmm-0005A2-96 for submit@debbugs.gnu.org; Thu, 17 Apr 2025 07:52:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u5NmQ-0003Sx-PA for bug-auctex@gnu.org; Thu, 17 Apr 2025 07:51:53 -0400 Received: from out-172.mta0.migadu.com ([91.218.175.172]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u5NmK-0005Sp-7Z for bug-auctex@gnu.org; Thu, 17 Apr 2025 07:51:42 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1744890693; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=Ndl2UR2AV+vVBlSVDO3WXTMtTkMAXWeBotajZ0cUt0g=; b=Omq6L+yTLN9Nx/q1VzDWeWfn52Xl831yGQqxx+ZgW+iKxbiC0xcWc5jXXC+zLriURE/4AV TjlYqEpSZa+yel0vrYv9OUq360NIIjtEOFQdixYw13jpdqV1Pt0nnDV++rpLSwvgg3Y7Ty 3OZp+JcjoNsB3KsA9WMrkxT/ZUEW0ZphJ4PaH7ikHXALG0vf2sUK7xbYVGqIgBGxF/YR0n LzEoH+GMhh7+tmGgYVNn8Po0NbnN0yaPPJUnQHJE441bc//0/hU3wEZgbuwLqfm7DyDdaT OGsL4FComjYD8RkmWLtLZnhDFowoCLzudZ8Izm4asp9MhAYg0rw2ONBFdRkdAQ== From: Jeremy Bryant Date: Thu, 17 Apr 2025 12:51:31 +0100 Message-ID: <878qnzngzg.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=91.218.175.172; envelope-from=jb@jeremybryant.net; helo=out-172.mta0.migadu.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-lisp-textmodes-reftex.el-checkdoc-fixes-comments-to-.patch >From 47d884899c61cfe17754a5c4acd7ea7391b3ed58 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant 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 --=-=-=-- From unknown Sat Jun 14 19:33:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#77864: [PATCH] - checkdoc fixes for reftex.el Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-auctex@gnu.org Resent-Date: Wed, 07 May 2025 21:40:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 77864 X-GNU-PR-Package: auctex X-GNU-PR-Keywords: patch To: 77864@debbugs.gnu.org X-Debbugs-Original-To: Jeremy Bryant via bug-auctex via Bug reporting list for AUCTeX X-Debbugs-Original-Cc: 77864@debbugs.gnu.org Received: via spool by submit@debbugs.gnu.org id=B.17466539952898 (code B ref -1); Wed, 07 May 2025 21:40:01 +0000 Received: (at submit) by debbugs.gnu.org; 7 May 2025 21:39:55 +0000 Received: from localhost ([127.0.0.1]:48885 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uCmUd-0000kg-Cy for submit@debbugs.gnu.org; Wed, 07 May 2025 17:39:55 -0400 Received: from lists.gnu.org ([2001:470:142::17]:48744) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uCmUZ-0000kF-Tl for submit@debbugs.gnu.org; Wed, 07 May 2025 17:39:52 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uCmUU-0006wu-KW for bug-auctex@gnu.org; Wed, 07 May 2025 17:39:46 -0400 Received: from out-176.mta1.migadu.com ([2001:41d0:203:375::b0]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uCmUT-0001R3-1o for bug-auctex@gnu.org; Wed, 07 May 2025 17:39:46 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1746653983; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=Vw43i8SdbQCFCd4Iq5y8KStjucmtwbPOw45osmfL4zc=; b=eSsLEKIVJLDZRFiCaboQZTw/0n3DNRW5wXMN0VDrvOf4mKSnCBQXlQaLy+3+4H2MN5b6xl sPYCbvPx9sVtSHtppFBwFA02WtW/WiVPjfLGSg3c7LY8xvEXKon9LRozMNpt334gIdCFX9 9QiuzXavbxbR0mFbpCsDdKCjUW16HIWtLKDeB9hzapX818F5TIedTY3D8mI2nlFukg5xHA wCalvdKeL8rdLtG421B3sUJEt5OIa462EQG+HaUMAvcX/g7BZMO/o9RQR/HsNbmj03kHXi rO3ynN1zi41A0FruBmTol36awajajBh/dAj8AGCBbCleFYK9bW5/k5xIQ6+R7Q== From: Jeremy Bryant In-Reply-To: <878qnzngzg.fsf@jeremybryant.net> (Jeremy Bryant via bug-auctex via Bug reporting list for AUCTeX's message of "Thu, 17 Apr 2025 12:51:31 +0100") References: <878qnzngzg.fsf@jeremybryant.net> Date: Wed, 07 May 2025 22:39:41 +0100 Message-ID: <874ixwrtgi.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: text/plain X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=2001:41d0:203:375::b0; envelope-from=jb@jeremybryant.net; helo=out-176.mta1.migadu.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) Jeremy Bryant via bug-auctex via Bug reporting list for AUCTeX writes: > 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. > > [2. text/x-diff; 0001-lisp-textmodes-reftex.el-checkdoc-fixes-comments-to-.patch]... > > _______________________________________________ > bug-auctex mailing list > bug-auctex@gnu.org > https://lists.gnu.org/mailman/listinfo/bug-auctex Ping! Any comments or suggestions, or is this good to install? From unknown Sat Jun 14 19:33:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#77864: [PATCH] - checkdoc fixes for reftex.el Resent-From: Arash Esbati Original-Sender: "Debbugs-submit" Resent-CC: bug-auctex@gnu.org Resent-Date: Wed, 07 May 2025 22:05:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 77864 X-GNU-PR-Package: auctex X-GNU-PR-Keywords: patch To: 77864@debbugs.gnu.org Cc: jb@jeremybryant.net X-Debbugs-Original-To: Jeremy Bryant via bug-auctex via Bug reporting list for AUCTeX X-Debbugs-Original-Cc: Jeremy Bryant , 77864@debbugs.gnu.org Received: via spool by submit@debbugs.gnu.org id=B.17466554528607 (code B ref -1); Wed, 07 May 2025 22:05:02 +0000 Received: (at submit) by debbugs.gnu.org; 7 May 2025 22:04:12 +0000 Received: from localhost ([127.0.0.1]:49017 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uCms7-0002Ef-ML for submit@debbugs.gnu.org; Wed, 07 May 2025 18:04:11 -0400 Received: from lists.gnu.org ([2001:470:142::17]:33966) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uCms5-0002EJ-1F for submit@debbugs.gnu.org; Wed, 07 May 2025 18:04:09 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uCmrz-0006le-BC for bug-auctex@gnu.org; Wed, 07 May 2025 18:04:03 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uCmry-0004Nx-Sn; Wed, 07 May 2025 18:04:02 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=GHfWDnlDClTouvWCwV3IIHKqbkRFoUAXI3zpdsJ6D2o=; b=jLKrTahLNV5gzR6rlDjc 4bskbOgV2pR/EoaEn9mkS6zzSjidGQsSb1kGzSULNeKRW4V/4mKZP039xZs455RqInKprNqT5AIKw jUlRwL82YSbzfCIDSHzZ5wu0JM5buQR8zqQy965HP4/TI0SIlO8/dQfM2pdSmIPYwbmZh31sSrb9l awjaody9kPAC0YPBZo0Siy/wMzL2TcBzZ+nCzY/VphthoyJnOMCjWU8htbAoeJpE5wmo/CiHvWDJI 5SNi8HAdGrGFFkp8YYfkGTIExCsXZ2W7OmCEW5WW8I06XrxdnhcCuoB1IJpuLl9oSQtU0s8Qup0ML bjZJn+rPZcyTsg==; From: Arash Esbati In-Reply-To: <874ixwrtgi.fsf@jeremybryant.net> References: <878qnzngzg.fsf@jeremybryant.net> <874ixwrtgi.fsf@jeremybryant.net> Date: Thu, 08 May 2025 00:03:59 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Jeremy Bryant via bug-auctex via Bug reporting list for AUCTeX writes: > Ping! > Any comments or suggestions, or is this good to install? Sorry for the delay, is on my list, but please be a little more patient as I'm currently busy with other stuff. Thanks, Arash From unknown Sat Jun 14 19:33:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#77864: [PATCH] - checkdoc fixes for reftex.el Resent-From: Arash Esbati Original-Sender: "Debbugs-submit" Resent-CC: bug-auctex@gnu.org Resent-Date: Mon, 12 May 2025 20:38:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 77864 X-GNU-PR-Package: auctex X-GNU-PR-Keywords: patch To: 77864@debbugs.gnu.org Cc: jb@jeremybryant.net Received: via spool by 77864-submit@debbugs.gnu.org id=B77864.1747082222480 (code B ref 77864); Mon, 12 May 2025 20:38:02 +0000 Received: (at 77864) by debbugs.gnu.org; 12 May 2025 20:37:02 +0000 Received: from localhost ([127.0.0.1]:55197 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uEZtW-00007f-Ca for submit@debbugs.gnu.org; Mon, 12 May 2025 16:37:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:45580) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uEZtU-000078-AE for 77864@debbugs.gnu.org; Mon, 12 May 2025 16:37:01 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uEZtO-0001l1-FE; Mon, 12 May 2025 16:36:54 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=/rfZmS/WZui2c39nXd9QO26Ui5fljJxaAEpDxm+wEcY=; b=QrrprWtWD+Z/AYhwMq9R oRGZMPFUQwyGrqVxHMTsTDnzJquUZ5i4OxGWvGFdB0u3mvrGGQzqRxcRav/0AC6U9l3wmsnkFmfuu 4p2OUyKaV5n4JFviJaiiZ38fZtuIgi93bTpoJ4Bbf19R7l4Rqd2dydsYjsJ5L1qZnLIEcoPs2vR24 i5oMJrfcDIP7B/MieNMPAzKP1bgj22+oMLO6tldNTqbQ8GuwlLU6cb2QT0224d1aVEMQOUT5iEkdC I2qdoJctVcg6huNu04+NKJtiuFxugtKYt6IxDSsyPvMTKa4kDZ2DdKNwO5Q5jBHHzNA/uiSYYpaTZ Zg3pW42mR1bzLg==; From: Arash Esbati In-Reply-To: References: <878qnzngzg.fsf@jeremybryant.net> <874ixwrtgi.fsf@jeremybryant.net> Date: Mon, 12 May 2025 22:36:49 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Arash Esbati writes: > Jeremy Bryant via bug-auctex via Bug reporting list for AUCTeX writes: > >> Ping! >> Any comments or suggestions, or is this good to install? > > Sorry for the delay, is on my list, but please be a little more patient > as I'm currently busy with other stuff. I tried to install your patch, but it doesn't apply: --8<---------------cut here---------------start------------->8--- Applying: * lisp/textmodes/reftex.el: checkdoc fixes, comments to docstrings error: patch failed: lisp/textmodes/reftex.el:276 error: lisp/textmodes/reftex.el: patch does not apply Patch failed at 0001 * lisp/textmodes/reftex.el: checkdoc fixes, comments to docstrings --8<---------------cut here---------------end--------------->8--- Can you please update your local git repo and resend the patch on top of the current HEAD? TIA. Can you also adjust the ChangeLog entry? It should look like this: --8<---------------cut here---------------start------------->8--- * lisp/textmodes/reftex.el (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 in functions. (reftex-silence-toc-markers): Convert comment to docstring and capitalize argument. (reftex-set-cite-format): Capitalize argument. --8<---------------cut here---------------end--------------->8--- Maybe you have another look at this[1]. TIA. Best, Arash Footnotes: [1] https://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE#n194 From unknown Sat Jun 14 19:33:01 2025 X-Loop: help-debbugs@gnu.org Subject: bug#77864: [PATCH] - checkdoc fixes for reftex.el Resent-From: Jeremy Bryant Original-Sender: "Debbugs-submit" Resent-CC: bug-auctex@gnu.org Resent-Date: Fri, 16 May 2025 22:37:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 77864 X-GNU-PR-Package: auctex X-GNU-PR-Keywords: patch To: Arash Esbati Cc: 77864@debbugs.gnu.org Received: via spool by 77864-submit@debbugs.gnu.org id=B77864.174743499917179 (code B ref 77864); Fri, 16 May 2025 22:37:03 +0000 Received: (at 77864) by debbugs.gnu.org; 16 May 2025 22:36:39 +0000 Received: from localhost ([127.0.0.1]:41565 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uG3fN-0004S9-DP for submit@debbugs.gnu.org; Fri, 16 May 2025 18:36:39 -0400 Received: from out-184.mta0.migadu.com ([2001:41d0:1004:224b::b8]:18999) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uG3fG-0004QH-BL for 77864@debbugs.gnu.org; Fri, 16 May 2025 18:36:30 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1747434978; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=aKlNODk5FDkbZzSse0PGwD32J0ZJ4w2pNZKLRbWB4kM=; b=R/o59W+n85DT+3m2xa+HdadlAqs3poh6Y7clF3SdVefeMnhSDlRfky7NH4ywk8wdB7uRqV ybJ5iA8ZIWt3RmT+e35a1tcRS9rL5gshAXsERizH708++8HFktubiK0OVD961V+1JEVJzO BMlK474YXeZEE63kCmz0GTzcoJ+St+w1nzn/IxyY45BKOKQqzsGZAp2GBXul+AFx9ozHr3 78+QmBunMzhxJasY7NVHBdndYVA3TWem1XPmyEGbe7zBLtANOV6BLkOeduEvcBIL2014Zf V4yMyNqhHmOiet2RbkAGNZJhPeeH75JEuTkB3PPrSkXr3Wd+qZ9IeL/gIRRyXQ== From: Jeremy Bryant In-Reply-To: (Arash Esbati's message of "Mon, 12 May 2025 22:36:49 +0200") References: <878qnzngzg.fsf@jeremybryant.net> <874ixwrtgi.fsf@jeremybryant.net> Date: Fri, 16 May 2025 23:36:17 +0100 Message-ID: <87r00op4im.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain Arash Esbati writes: > Arash Esbati writes: > > I tried to install your patch, but it doesn't apply: > ... > > Maybe you have another look at this[1]. > > TIA. Best, Arash > > Footnotes: > [1] https://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE#n194 OK, revised patch from current master. Does this apply now? Thanks in advance --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-lisp-textmodes-reftex.el-checkdoc-fixes-comments-to-.patch >From 144d4ddd34527c396021bb7ae8b26eacfe9ca5c0 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Fri, 16 May 2025 23:28:13 +0100 Subject: [PATCH] ; * lisp/textmodes/reftex.el: checkdoc fixes, comments to docstrings (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 in functions. (reftex-silence-toc-markers): Convert comment to docstring and capitalize argument. (reftex-set-cite-format): Capitalize argument. --- lisp/textmodes/reftex.el | 202 +++++++++++++++++++-------------------- 1 file changed, 100 insertions(+), 102 deletions(-) diff --git a/lisp/textmodes/reftex.el b/lisp/textmodes/reftex.el index ee217804d8f..6de6e99625a 100644 --- a/lisp/textmodes/reftex.el +++ b/lisp/textmodes/reftex.el @@ -316,7 +316,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--remove-buffer-from-master-index () @@ -372,11 +372,11 @@ 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. - (with-current-buffer (or (buffer-base-buffer) (current-buffer)) + "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'." +r (with-current-buffer (or (buffer-base-buffer) (current-buffer)) (let ;; Set master to a file name (possibly non-existent), or nil: ((master @@ -445,14 +445,14 @@ reftex-TeX-master-file (or master (current-buffer)))))) (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." @@ -463,8 +463,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)) @@ -697,7 +698,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)) @@ -777,7 +778,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))) @@ -789,8 +790,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...") ;; Update AUCTeX style information @@ -1129,8 +1129,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))) @@ -1152,11 +1152,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." ;; Make sure we have the symbols tied (if (eq reftex-docstruct-symbol nil) @@ -1196,7 +1196,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))) @@ -1292,7 +1292,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)) @@ -1316,7 +1316,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)) @@ -1401,9 +1401,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) @@ -1425,13 +1425,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 @@ -1485,8 +1485,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) @@ -1503,8 +1503,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) @@ -1513,8 +1513,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) "//")) @@ -1530,7 +1530,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) @@ -1546,7 +1546,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) @@ -1554,8 +1554,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 @@ -1576,26 +1576,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 @@ -1606,7 +1606,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 @@ -1619,7 +1619,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) @@ -1627,7 +1627,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) @@ -1636,11 +1636,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)) @@ -1651,10 +1651,9 @@ 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)) @@ -1666,20 +1665,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 @@ -1691,9 +1690,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) @@ -1713,8 +1712,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 @@ -1724,8 +1723,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. @@ -1743,9 +1742,8 @@ 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 @@ -1783,7 +1781,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))) @@ -1794,16 +1792,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 returns 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 (if (bufferp file) file @@ -1849,7 +1847,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) @@ -1868,8 +1866,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 @@ -1885,8 +1883,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 @@ -1917,9 +1915,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 @@ -2055,7 +2053,7 @@ reftex-convert-string string)) (defun reftex-nicify-text (text) - ;; Make TEXT nice for inclusion as context into label menu. + "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))) @@ -2080,7 +2078,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) @@ -2088,8 +2086,8 @@ 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)) @@ -2107,7 +2105,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)) @@ -2121,10 +2119,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)) @@ -2159,7 +2157,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 --=-=-=-- From unknown Sat Jun 14 19:33:01 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Jeremy Bryant Subject: bug#77864: closed (Re: bug#77864: [PATCH] - checkdoc fixes for reftex.el) Message-ID: References: <878qnzngzg.fsf@jeremybryant.net> X-Gnu-PR-Message: they-closed 77864 X-Gnu-PR-Package: auctex X-Gnu-PR-Keywords: patch Reply-To: 77864@debbugs.gnu.org Date: Fri, 30 May 2025 17:50:03 +0000 Content-Type: multipart/mixed; boundary="----------=_1748627403-29185-1" This is a multi-part message in MIME format... ------------=_1748627403-29185-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #77864: [PATCH] - checkdoc fixes for reftex.el which was filed against the auctex package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 77864@debbugs.gnu.org. --=20 77864: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D77864 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1748627403-29185-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 77864-done) by debbugs.gnu.org; 30 May 2025 17:49:40 +0000 Received: from localhost ([127.0.0.1]:50384 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1uL3rQ-0007Z8-9c for submit@debbugs.gnu.org; Fri, 30 May 2025 13:49:40 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34538) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1uL3rM-0007Yk-Li for 77864-done@debbugs.gnu.org; Fri, 30 May 2025 13:49:39 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uL3rH-0005El-9H; Fri, 30 May 2025 13:49:31 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=HKQZAuEOFjdOZSOei6BMVINaOSngRdu4oBBvN/u5RaU=; b=IX6Ai6a8zBDs0BZM4o8I OEJ01Q9M5mRKnC+os/Q/4XB4jfGgF7eyxSPQnvHfaR9KahxfDHUur7T0cR9Tz0HdmUBWqH6y0vjCW Ed5k4BYlbQd84qmfDp7GKBQZo8xLWYQDtiDBK6vV9oM/je3LI6olF9HklUXjNM0mLqfqsJ77Lriw8 VUNlmHKCcUDCvpm6gZEKaYXfZRC4Yruh9DQtvnXIzEbGCExbUQ+cB06OucB94YqJ0/ORuKBRdT2fr XNLjRqxHou57OfNJ8OsoGA3BdsmTXfB41AsHCh0mYroJSewyyFioKOU1LxQRjlkov1YkS8IBfSVZ3 EennMBNSs8ECOQ==; From: Arash Esbati To: Jeremy Bryant Subject: Re: bug#77864: [PATCH] - checkdoc fixes for reftex.el In-Reply-To: <87r00op4im.fsf@jeremybryant.net> References: <878qnzngzg.fsf@jeremybryant.net> <874ixwrtgi.fsf@jeremybryant.net> <87r00op4im.fsf@jeremybryant.net> Date: Fri, 30 May 2025 19:49:27 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 77864-done Cc: 77864-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Jeremy Bryant writes: > OK, revised patch from current master. > > Does this apply now? Yes, thanks. I installed that change, closing. Best, Arash ------------=_1748627403-29185-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 17 Apr 2025 11:52:12 +0000 Received: from localhost ([127.0.0.1]:46064 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1u5Nms-0005Bs-W8 for submit@debbugs.gnu.org; Thu, 17 Apr 2025 07:52:12 -0400 Received: from lists.gnu.org ([2001:470:142::17]:36066) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1u5Nmm-0005A2-96 for submit@debbugs.gnu.org; Thu, 17 Apr 2025 07:52:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u5NmQ-0003Sx-PA for bug-auctex@gnu.org; Thu, 17 Apr 2025 07:51:53 -0400 Received: from out-172.mta0.migadu.com ([91.218.175.172]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u5NmK-0005Sp-7Z for bug-auctex@gnu.org; Thu, 17 Apr 2025 07:51:42 -0400 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1744890693; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=Ndl2UR2AV+vVBlSVDO3WXTMtTkMAXWeBotajZ0cUt0g=; b=Omq6L+yTLN9Nx/q1VzDWeWfn52Xl831yGQqxx+ZgW+iKxbiC0xcWc5jXXC+zLriURE/4AV TjlYqEpSZa+yel0vrYv9OUq360NIIjtEOFQdixYw13jpdqV1Pt0nnDV++rpLSwvgg3Y7Ty 3OZp+JcjoNsB3KsA9WMrkxT/ZUEW0ZphJ4PaH7ikHXALG0vf2sUK7xbYVGqIgBGxF/YR0n LzEoH+GMhh7+tmGgYVNn8Po0NbnN0yaPPJUnQHJE441bc//0/hU3wEZgbuwLqfm7DyDdaT OGsL4FComjYD8RkmWLtLZnhDFowoCLzudZ8Izm4asp9MhAYg0rw2ONBFdRkdAQ== From: Jeremy Bryant To: bug-auctex@gnu.org Subject: [PATCH] - checkdoc fixes for reftex.el Date: Thu, 17 Apr 2025 12:51:31 +0100 Message-ID: <878qnzngzg.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=91.218.175.172; envelope-from=jb@jeremybryant.net; helo=out-172.mta0.migadu.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-lisp-textmodes-reftex.el-checkdoc-fixes-comments-to-.patch >From 47d884899c61cfe17754a5c4acd7ea7391b3ed58 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant 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 --=-=-=-- ------------=_1748627403-29185-1--