* RE: no doc string for tag functions and variables
2008-02-11 0:17 ` Richard Stallman
@ 2008-02-11 2:23 ` Drew Adams
2008-02-11 21:10 ` Richard Stallman
0 siblings, 1 reply; 4+ messages in thread
From: Drew Adams @ 2008-02-11 2:23 UTC (permalink / raw)
To: rms; +Cc: emacs-pretest-bug
[-- Attachment #1: Type: text/plain, Size: 359 bytes --]
> How about writing doc strings and sending us a patch.
Attached is a patch. Amend as needed.
I transferred existing comments to doc strings, rewording a bit in some
cases.
I tried only to understand the existing comments; I did not try to
understand uncommented code to guess what the doc strings should be. So some
functions still have no doc strings.
[-- Attachment #2: etags-2008-02-10.patch --]
[-- Type: application/octet-stream, Size: 25641 bytes --]
diff -c -w etags-2008-02-10.el etags-2008-02-10-patched.el
*** etags-2008-02-10.el Sun Feb 10 17:33:54 2008
--- etags-2008-02-10-patched.el Sun Feb 10 18:20:22 2008
***************
*** 258,268 ****
(defvar verify-tags-table-function nil
"Function to return t if current buffer contains valid tags file.")
\f
- ;; Initialize the tags table in the current buffer.
- ;; Returns non-nil if it is a valid tags table. On
- ;; non-nil return, the tags table state variable are
- ;; made buffer-local and initialized to nil.
(defun initialize-new-tags-table ()
(set (make-local-variable 'tags-table-files) nil)
(set (make-local-variable 'tags-completion-table) nil)
(set (make-local-variable 'tags-included-tables) nil)
--- 258,268 ----
(defvar verify-tags-table-function nil
"Function to return t if current buffer contains valid tags file.")
\f
(defun initialize-new-tags-table ()
+ "Initialize the tags table in the current buffer.
+ Returns non-nil if it is a valid tags table. On
+ non-nil return, the tags table state variables are
+ made buffer-local and initialized to nil."
(set (make-local-variable 'tags-table-files) nil)
(set (make-local-variable 'tags-completion-table) nil)
(set (make-local-variable 'tags-included-tables) nil)
***************
*** 357,369 ****
(setq tags-table-computed-list-for compute-for
tags-table-computed-list (nreverse computed))))))
- ;; Extend `tags-table-computed-list' to remove the first `t' placeholder.
- ;; An element of the list that is `t' is a placeholder indicating that the
- ;; preceding element is a table that has not been read into core and might
- ;; contain included tables to search. On return, the first placeholder
- ;; element will be gone and the element before it read into core and its
- ;; included tables inserted into the list.
(defun tags-table-extend-computed-list ()
(let ((list tags-table-computed-list))
(while (not (eq (nth 1 list) t))
(setq list (cdr list)))
--- 357,369 ----
(setq tags-table-computed-list-for compute-for
tags-table-computed-list (nreverse computed))))))
(defun tags-table-extend-computed-list ()
+ "Extend `tags-table-computed-list' to remove the first `t' placeholder.
+ An element of the list that is `t' is a placeholder indicating that the
+ preceding element is a table that has not been read into core and might
+ contain included tables to search. On return, the first placeholder
+ element will be gone and the element before it read into core and its
+ included tables inserted into the list."
(let ((list tags-table-computed-list))
(while (not (eq (nth 1 list) t))
(setq list (cdr list)))
***************
*** 398,405 ****
;; It was not a valid table, so just remove the following placeholder.
(setcdr list (cdr (cdr list)))))))
- ;; Expand tags table name FILE into a complete file name.
(defun tags-expand-table-name (file)
(setq file (expand-file-name file))
(if (file-directory-p file)
(expand-file-name "TAGS" file)
--- 398,405 ----
;; It was not a valid table, so just remove the following placeholder.
(setcdr list (cdr (cdr list)))))))
(defun tags-expand-table-name (file)
+ "Expand tags table name FILE into a complete file name."
(setq file (expand-file-name file))
(if (file-directory-p file)
(expand-file-name "TAGS" file)
***************
*** 408,413 ****
--- 408,416 ----
;; Like member, but comparison is done after tags-expand-table-name on both
;; sides and elements of LIST that are t are skipped.
(defun tags-table-list-member (file list)
+ "Like (member FILE LIST) after applying `tags-expand-table-name'.
+ That is, apply `tags-expand-table-name' to FILE and elements of LIST.
+ LIST elements equal to t are skipped."
(setq file (tags-expand-table-name file))
(while (and list
(or (eq (car list) t)
***************
*** 464,469 ****
--- 467,478 ----
;; we return. If CORE-ONLY is non-nil, check only tags tables that are
;; already in buffers--don't visit any new files.
(defun tags-table-including (this-file core-only)
+ "Search current tags tables for tags for THIS-FILE.
+ Subroutine of `visit-tags-table-buffer'.
+ Looks for a tags table that has such tags or that includes a table
+ that has them. Returns the name of the first such table.
+ Non-nil CORE-ONLY means check only tags tables that are already in
+ buffers. Nil CORE-ONLY is ignored."
(let ((tables tags-table-computed-list)
(found nil))
;; Loop over the list, looking for a table containing tags for THIS-FILE.
***************
*** 509,517 ****
;; included the one we found.
could-be))))
- ;; Subroutine of visit-tags-table-buffer. Move tags-table-list-pointer
- ;; along and set tags-file-name. Returns nil when out of tables.
(defun tags-next-table ()
;; If there is a placeholder element next, compute the list to replace it.
(while (eq (nth 1 tags-table-list-pointer) t)
(tags-table-extend-computed-list))
--- 518,527 ----
;; included the one we found.
could-be))))
(defun tags-next-table ()
+ "Move `tags-table-list-pointer' along and set `tags-file-name'.
+ Subroutine of `visit-tags-table-buffer'.\
+ Returns nil when out of tables."
;; If there is a placeholder element next, compute the list to replace it.
(while (eq (nth 1 tags-table-list-pointer) t)
(tags-table-extend-computed-list))
***************
*** 742,751 ****
(or tags-included-tables
(setq tags-included-tables (funcall tags-included-tables-function))))
\f
- ;; Build tags-completion-table on demand. The single current tags table
- ;; and its included tags tables (and their included tables, etc.) have
- ;; their tags included in the completion table.
(defun tags-completion-table ()
(or tags-completion-table
;; No cached value for this buffer.
(condition-case ()
--- 752,761 ----
(or tags-included-tables
(setq tags-included-tables (funcall tags-included-tables-function))))
\f
(defun tags-completion-table ()
+ "Build `tags-completion-table' on demand.
+ The tags included in the completion table are those in the current
+ tags table and its (recursively) included tags tables."
(or tags-completion-table
;; No cached value for this buffer.
(condition-case ()
***************
*** 769,777 ****
(quit (message "Tags completion table construction aborted.")
(setq tags-completion-table nil)))))
- ;; Completion function for tags. Does normal try-completion,
- ;; but builds tags-completion-table on demand.
(defun tags-complete-tag (string predicate what)
(save-excursion
;; If we need to ask for the tag table, allow that.
(let ((enable-recursive-minibuffers t))
--- 779,788 ----
(quit (message "Tags completion table construction aborted.")
(setq tags-completion-table nil)))))
(defun tags-complete-tag (string predicate what)
+ "Completion function for tags.
+ Does normal `try-completion', but builds `tags-completion-table' on
+ demand."
(save-excursion
;; If we need to ask for the tag table, allow that.
(let ((enable-recursive-minibuffers t))
***************
*** 780,787 ****
(all-completions string (tags-completion-table) predicate)
(try-completion string (tags-completion-table) predicate))))
\f
- ;; Read a tag name from the minibuffer with defaulting and completion.
(defun find-tag-tag (string)
(let* ((completion-ignore-case (if (memq tags-case-fold-search '(t nil))
tags-case-fold-search
case-fold-search))
--- 791,798 ----
(all-completions string (tags-completion-table) predicate)
(try-completion string (tags-completion-table) predicate))))
\f
(defun find-tag-tag (string)
+ "Read a tag name, with defaulting and completion."
(let* ((completion-ignore-case (if (memq tags-case-fold-search '(t nil))
tags-case-fold-search
case-fold-search))
***************
*** 802,809 ****
(defvar last-tag nil
"Last tag found by \\[find-tag].")
- ;; Get interactive args for find-tag{-noselect,-other-window,-regexp}.
(defun find-tag-interactive (prompt &optional no-default)
(if (and current-prefix-arg last-tag)
(list nil (if (< (prefix-numeric-value current-prefix-arg) 0)
'-
--- 813,822 ----
(defvar last-tag nil
"Last tag found by \\[find-tag].")
(defun find-tag-interactive (prompt &optional no-default)
+ "Get interactive arguments for tag functions.
+ The functions using this are `find-tag-noselect',
+ `find-tag-other-window', and `find-tag-regexp'."
(if (and current-prefix-arg last-tag)
(list nil (if (< (prefix-numeric-value current-prefix-arg) 0)
'-
***************
*** 812,818 ****
(read-string prompt)
(find-tag-tag prompt)))))
! (defvar find-tag-history nil)
;; Dynamic bondage:
(eval-when-compile
--- 825,831 ----
(read-string prompt)
(find-tag-tag prompt)))))
! (defvar find-tag-history nil) ; Doc string?
;; Dynamic bondage:
(eval-when-compile
***************
*** 1028,1053 ****
(goto-char (marker-position marker))
(set-marker marker nil nil)))
\f
! ;; Internal tag finding function.
!
! ;; PATTERN is a string to pass to second arg SEARCH-FORWARD-FUNC, and to
! ;; any member of the function list ORDER (third arg). If ORDER is nil,
! ;; use saved state to continue a previous search.
!
! ;; Fourth arg NEXT-LINE-AFTER-FAILURE-P is non-nil if after a failed match,
! ;; point should be moved to the next line.
!
! ;; Fifth arg MATCHING is a string, an English '-ing' word, to be used in
! ;; an error message.
!
! ;; Algorithm is as follows. For each qualifier-func in ORDER, go to
! ;; beginning of tags file, and perform inner loop: for each naive match for
! ;; PATTERN found using SEARCH-FORWARD-FUNC, qualify the naive match using
! ;; qualifier-func. If it qualifies, go to the specified line in the
! ;; specified source file and return. Qualified matches are remembered to
! ;; avoid repetition. State is saved so that the loop can be continued.
!
! (defvar tag-lines-already-matched nil) ;matches remembered here between calls
(defun find-tag-in-order (pattern
search-forward-func
--- 1041,1048 ----
(goto-char (marker-position marker))
(set-marker marker nil nil)))
\f
! (defvar tag-lines-already-matched nil
! "Matches remembered between calls.") ; Doc string: calls to what?
(defun find-tag-in-order (pattern
search-forward-func
***************
*** 1055,1060 ****
--- 1050,1072 ----
next-line-after-failure-p
matching
first-search)
+ "Internal tag-finding function.
+ PATTERN is a string to pass to arg SEARCH-FORWARD-FUNC, and to any
+ member of the function list ORDER. If ORDER is nil, use saved state
+ to continue a previous search.
+
+ Arg NEXT-LINE-AFTER-FAILURE-P is non-nil if after a failed match,
+ point should be moved to the next line.
+
+ Arg MATCHING is a string, an English `-ing' word, to be used in an
+ error message."
+ ;; Algorithm is as follows:
+ ;; For each qualifier-func in ORDER, go to beginning of tags file, and
+ ;; perform inner loop: for each naive match for PATTERN found using
+ ;; SEARCH-FORWARD-FUNC, qualify the naive match using qualifier-func. If
+ ;; it qualifies, go to the specified line in the specified source file
+ ;; and return. Qualified matches are remembered to avoid repetition.
+ ;; State is saved so that the loop can be continued.
(let (file ;name of file containing tag
tag-info ;where to find the tag in FILE
(first-table t)
***************
*** 1147,1156 ****
(current-buffer))))
(defun tag-find-file-of-tag-noselect (file)
! ;; Find the right line in the specified file.
! ;; If we are interested in compressed-files,
! ;; we search files with extensions.
! ;; otherwise only the real file.
(let* ((buffer-search-extensions (if (featurep 'jka-compr)
tags-compression-info-list
'("")))
--- 1159,1167 ----
(current-buffer))))
(defun tag-find-file-of-tag-noselect (file)
! "Find the right line in the specified FILE."
! ;; If interested in compressed-files, search files with extensions.
! ;; Otherwise, search only the real file.
(let* ((buffer-search-extensions (if (featurep 'jka-compr)
tags-compression-info-list
'("")))
***************
*** 1180,1186 ****
(error "File %s not found" file))
(set-buffer the-buffer))))
! (defun tag-find-file-of-tag (file)
(let ((buf (tag-find-file-of-tag-noselect file)))
(condition-case nil
(switch-to-buffer buf)
--- 1191,1197 ----
(error "File %s not found" file))
(set-buffer the-buffer))))
! (defun tag-find-file-of-tag (file) ; Doc string?
(let ((buf (tag-find-file-of-tag-noselect file)))
(condition-case nil
(switch-to-buffer buf)
***************
*** 1188,1196 ****
\f
;; `etags' TAGS file format support.
- ;; If the current buffer is a valid etags TAGS file, give it local values of
- ;; the tags table format variables, and return non-nil.
(defun etags-recognize-tags-table ()
(and (etags-verify-tags-table)
;; It is annoying to flash messages on the screen briefly,
;; and this message is not useful. -- rms
--- 1199,1208 ----
\f
;; `etags' TAGS file format support.
(defun etags-recognize-tags-table ()
+ "If `etags-verify-tags-table', make buffer-local format variables.
+ If current buffer is a valid etags TAGS file, then give it
+ buffer-local values of tags table format variables."
(and (etags-verify-tags-table)
;; It is annoying to flash messages on the screen briefly,
;; and this message is not useful. -- rms
***************
*** 1225,1231 ****
;; Use eq instead of = in case char-after returns nil.
(eq (char-after (point-min)) ?\f))
! (defun etags-file-of-tag (&optional relative)
(save-excursion
(re-search-backward "\f\n\\([^\n]+\\),[0-9]*\n")
(let ((str (buffer-substring (match-beginning 1) (match-end 1))))
--- 1237,1243 ----
;; Use eq instead of = in case char-after returns nil.
(eq (char-after (point-min)) ?\f))
! (defun etags-file-of-tag (&optional relative) ; Doc string?
(save-excursion
(re-search-backward "\f\n\\([^\n]+\\),[0-9]*\n")
(let ((str (buffer-substring (match-beginning 1) (match-end 1))))
***************
*** 1235,1241 ****
(file-truename default-directory))))))
! (defun etags-tags-completion-table ()
(let ((table (make-vector 511 0))
(progress-reporter
(make-progress-reporter
--- 1247,1253 ----
(file-truename default-directory))))))
! (defun etags-tags-completion-table () ; Doc string?
(let ((table (make-vector 511 0))
(progress-reporter
(make-progress-reporter
***************
*** 1265,1271 ****
table)))
table))
! (defun etags-snarf-tag (&optional use-explicit)
(let (tag-text line startpos explicit-start)
(if (save-excursion
(forward-line -1)
--- 1277,1283 ----
table)))
table))
! (defun etags-snarf-tag (&optional use-explicit) ; Doc string?
(let (tag-text line startpos explicit-start)
(if (save-excursion
(forward-line -1)
***************
*** 1305,1319 ****
(forward-line 1)
(cons tag-text (cons line startpos))))
- ;; TAG-INFO is a cons (TEXT LINE . POSITION) where TEXT is the initial part
- ;; of a line containing the tag and POSITION is the character position of
- ;; TEXT within the file (starting from 1); LINE is the line number. If
- ;; TEXT is t, it means the tag refers to exactly LINE or POSITION
- ;; (whichever is present, LINE having preference, no searching. Either
- ;; LINE or POSITION may be nil; POSITION is used if present. If the tag
- ;; isn't exactly at the given position then look around that position using
- ;; a search window which expands until it hits the start of file.
(defun etags-goto-tag-location (tag-info)
(let ((startpos (cdr (cdr tag-info)))
(line (car (cdr tag-info)))
offset found pat)
--- 1317,1336 ----
(forward-line 1)
(cons tag-text (cons line startpos))))
(defun etags-goto-tag-location (tag-info)
+ "Go to location of tag specified by TAG-INFO.
+ TAG-INFO is a cons (TEXT LINE . POSITION).
+ TEXT is the initial part of a line containing the tag.
+ LINE is the line number.
+ POSITION is the (one-based) char position of TEXT within the file.
+
+ If TEXT is t, it means the tag refers to exactly LINE or POSITION,
+ whichever is present, LINE having preference, no searching.
+ Either LINE or POSITION can be nil. POSITION is used if present.
+
+ If the tag isn't exactly at the given position, then look near that
+ position using a search window that expands progressively until it
+ hits the start of file."
(let ((startpos (cdr (cdr tag-info)))
(line (car (cdr tag-info)))
offset found pat)
***************
*** 1362,1368 ****
(forward-char 1))
(beginning-of-line)))
! (defun etags-list-tags (file)
(goto-char (point-min))
(when (re-search-forward (concat "\f\n" "\\(" file "\\)" ",") nil t)
(let ((path (save-excursion (forward-line 1) (file-of-tag)))
--- 1379,1385 ----
(forward-char 1))
(beginning-of-line)))
! (defun etags-list-tags (file) ; Doc string?
(goto-char (point-min))
(when (re-search-forward (concat "\f\n" "\\(" file "\\)" ",") nil t)
(let ((path (save-excursion (forward-line 1) (file-of-tag)))
***************
*** 1435,1441 ****
(funcall ins-symb (car sy))))
(sort-lines nil beg (point))))))
! (defun etags-tags-apropos (string)
(when tags-apropos-verbose
(princ "Tags in file `")
(tags-with-face 'highlight (princ buffer-file-name))
--- 1452,1458 ----
(funcall ins-symb (car sy))))
(sort-lines nil beg (point))))))
! (defun etags-tags-apropos (string) ; Doc string?
(when tags-apropos-verbose
(princ "Tags in file `")
(tags-with-face 'highlight (princ buffer-file-name))
***************
*** 1496,1502 ****
(message nil))
(when tags-apropos-verbose (princ "\n")))
! (defun etags-tags-table-files ()
(let ((files nil)
beg)
(goto-char (point-min))
--- 1513,1519 ----
(message nil))
(when tags-apropos-verbose (princ "\n")))
! (defun etags-tags-table-files () ; Doc string?
(let ((files nil)
beg)
(goto-char (point-min))
***************
*** 1508,1514 ****
(setq files (cons (buffer-substring beg (1- (point))) files))))
(nreverse files)))
! (defun etags-tags-included-tables ()
(let ((files nil)
beg)
(goto-char (point-min))
--- 1525,1531 ----
(setq files (cons (buffer-substring beg (1- (point))) files))))
(nreverse files)))
! (defun etags-tags-included-tables () ; Doc string?
(let ((files nil)
beg)
(goto-char (point-min))
***************
*** 1524,1532 ****
\f
;; Empty tags file support.
- ;; Recognize an empty file and give it local values of the tags table format
- ;; variables which do nothing.
(defun tags-recognize-empty-tags-table ()
(and (zerop (buffer-size))
(mapc (lambda (sym) (set (make-local-variable sym) 'ignore))
'(tags-table-files-function
--- 1541,1550 ----
\f
;; Empty tags file support.
(defun tags-recognize-empty-tags-table ()
+ "Returns non-nil if current buffer is empty.
+ If empty, make buffer-local values of the tags table format variables
+ that do nothing."
(and (zerop (buffer-size))
(mapc (lambda (sym) (set (make-local-variable sym) 'ignore))
'(tags-table-files-function
***************
*** 1560,1574 ****
--- 1578,1597 ----
;; exact file name match, i.e. searched tag must match complete file
;; name including directories parts if there are some.
(defun tag-exact-file-name-match-p (tag)
+ "Return non-nil if TAG matches complete file name.
+ Any directory part of the file name is also matched."
(and (looking-at ",[0-9\n]")
(save-excursion (backward-char (+ 2 (length tag)))
(looking-at "\f\n"))))
+
;; file name match as above, but searched tag must match the file
;; name not including the directories if there are some.
(defun tag-file-name-match-p (tag)
+ "Returns non-nil if TAG matches file name, excluding directory part."
(and (looking-at ",[0-9\n]")
(save-excursion (backward-char (1+ (length tag)))
(looking-at "/"))))
+
;; this / to detect we are after a directory separator is ok for unix,
;; is there a variable that contains the regexp for directory separator
;; on whatever operating system ?
***************
*** 1577,1582 ****
--- 1600,1607 ----
;; t if point is at a tag line that matches TAG exactly.
;; point should be just after a string that matches TAG.
(defun tag-exact-match-p (tag)
+ "Returns non-nil if current tag line matches TAG exactly.
+ Point should be just after a string that matches TAG."
;; The match is really exact if there is an explicit tag name.
(or (and (eq (char-after (point)) ?\001)
(eq (char-after (- (point) (length tag) 1)) ?\177))
***************
*** 1586,1591 ****
--- 1611,1618 ----
;; t if point is at a tag line that has an implicit name.
;; point should be just after a string that matches TAG.
(defun tag-implicit-name-match-p (tag)
+ "Returns non-nil if current tag line has an implicit name.
+ Point should be just after a string that matches TAG."
;; Look at the comment of the make_tag function in lib-src/etags.c for
;; a textual description of the four rules.
(and (string-match "^[^ \t()=,;]+$" tag) ;rule #1
***************
*** 1597,1602 ****
--- 1624,1631 ----
;; t if point is at a tag line that matches TAG as a symbol.
;; point should be just after a string that matches TAG.
(defun tag-symbol-match-p (tag)
+ "Returns non-nil if current tag line matches TAG as a symbol.
+ Point should be just after a string that matches TAG."
(and (looking-at "\\Sw.*\177") (looking-at "\\S_.*\177")
(save-excursion
(backward-char (1+ (length tag)))
***************
*** 1605,1610 ****
--- 1634,1641 ----
;; t if point is at a tag line that matches TAG as a word.
;; point should be just after a string that matches TAG.
(defun tag-word-match-p (tag)
+ "Returns non-nil if current tag line matches TAG as a word.
+ Point should be just after a string that matches TAG."
(and (looking-at "\\b.*\177")
(save-excursion (backward-char (length tag))
(looking-at "\\b"))))
***************
*** 1612,1617 ****
--- 1643,1651 ----
;; partial file name match, i.e. searched tag must match a substring
;; of the file name (potentially including a directory separator).
(defun tag-partial-file-name-match-p (tag)
+ "Returns non-nil if current tag matches file name.
+ This is a substring match, and it can include directory separators.
+ Point should be just after a string that matches TAG."
(and (looking-at ".*,[0-9\n]")
(save-excursion (beginning-of-line)
(backward-char 2)
***************
*** 1619,1628 ****
--- 1653,1664 ----
;; t if point is in a tag line with a tag containing TAG as a substring.
(defun tag-any-match-p (tag)
+ "Returns non-nil if current tag line contains TAG as a substring."
(looking-at ".*\177"))
;; t if point is at a tag line that matches RE as a regexp.
(defun tag-re-match-p (re)
+ "Returns non-nil if current tag line matches regexp RE."
(save-excursion
(beginning-of-line)
(let ((bol (point)))
***************
*** 1845,1851 ****
tags-loop-operate `(perform-replace ',from ',to t t ',delimited))
(tags-loop-continue (or file-list-form t)))
\f
! (defun tags-complete-tags-table-file (string predicate what)
(save-excursion
;; If we need to ask for the tag table, allow that.
(let ((enable-recursive-minibuffers t))
--- 1881,1887 ----
tags-loop-operate `(perform-replace ',from ',to t t ',delimited))
(tags-loop-continue (or file-list-form t)))
\f
! (defun tags-complete-tags-table-file (string predicate what) ; Doc string?
(save-excursion
;; If we need to ask for the tag table, allow that.
(let ((enable-recursive-minibuffers t))
***************
*** 1966,1972 ****
(set-buffer-modified-p nil)
(select-tags-table-mode))
! (defvar select-tags-table-mode-map
(let ((map (make-sparse-keymap)))
(set-keymap-parent map button-buffer-map)
(define-key map "t" 'push-button)
--- 2002,2008 ----
(set-buffer-modified-p nil)
(select-tags-table-mode))
! (defvar select-tags-table-mode-map ; Doc string?
(let ((map (make-sparse-keymap)))
(set-keymap-parent map button-buffer-map)
(define-key map "t" 'push-button)
Diff finished. Sun Feb 10 18:20:58 2008
^ permalink raw reply [flat|nested] 4+ messages in thread