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