Add many doc strings.

2 files changed, 109 insertions, 68 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 31e4ebc5da7..660a1072ee7 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2008-02-11  Drew Adams  <drew.adams@oracle.com>
+
+        * progmodes/etags.el: Add many doc strings.
+
 2008-02-11  Jason Rumney  <jasonr@gnu.org>
 
         * ldefs-boot.el: Regenerated.
diff --git a/lisp/progmodes/etags.el b/lisp/progmodes/etags.el
index fcc05b14d6c..e18491ad97a 100644
--- a/lisp/progmodes/etags.el
+++ b/lisp/progmodes/etags.el
@@ -258,11 +258,11 @@ One argument, the tag info returned by `snarf-tag-function'.")
 (defvar verify-tags-table-function nil
   "Function to return t if current buffer contains valid tags file.")
 
-;; 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 ()
+  "Initialize the tags table in the current buffer.
+Return non-nil if it is a valid tags table, and
+in that case, also make the tags table state variables 
+buffer-local and set them 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,13 +357,13 @@ file the tag was in."
           (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 ()
+  "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 in and might
+contain included tables to search.  This function reads in the first
+such table and puts its included tables into the list."
   (let ((list tags-table-computed-list))
     (while (not (eq (nth 1 list) t))
       (setq list (cdr list)))
@@ -398,8 +398,8 @@ file the tag was in."
         ;; 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)
+  "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,6 +408,10 @@ file the tag was in."
 ;; 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'.
+More precisely, apply `tags-expand-table-name' to FILE
+and each element of LIST, returning the link whose car is the first match.
+If an element of LIST is t, ignore it."
   (setq file (tags-expand-table-name file))
   (while (and list
               (or (eq (car list) t)
@@ -464,6 +468,12 @@ Returns non-nil if it is a valid table."
 ;; 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,9 +519,10 @@ Returns non-nil if it is a valid table."
           ;; 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 ()
+  "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))
@@ -672,7 +683,7 @@ Returns t if it visits a tags table, or nil if there are no more in the list."
                                           tags-table-set-list)))
                           ;; Clear out buffers holding old tables.
                           (dolist (table tags-table-list)
-                            ;; The list can contain items `t'.
+                            ;; The list can contain items t.
                             (if (stringp table)
                                 (let ((buffer (find-buffer-visiting table)))
                               (if buffer
@@ -742,10 +753,10 @@ Assumes the tags table is the current buffer."
   (or tags-included-tables
       (setq tags-included-tables (funcall tags-included-tables-function))))
 
-;; 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 ()
+  "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,9 +780,10 @@ Assumes the tags table is the current buffer."
         (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)
+  "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,8 +792,8 @@ Assumes the tags table is the current buffer."
         (all-completions string (tags-completion-table) predicate)
       (try-completion string (tags-completion-table) predicate))))
 
-;; Read a tag name from the minibuffer with defaulting and completion.
 (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,8 +814,10 @@ Assumes the tags table is the current buffer."
 (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)
+  "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,7 +826,7 @@ Assumes the tags table is the current buffer."
               (read-string prompt)
             (find-tag-tag prompt)))))
 
-(defvar find-tag-history nil)
+(defvar find-tag-history nil) ; Doc string?
 
 ;; Dynamic bondage:
 (eval-when-compile
@@ -1028,26 +1042,8 @@ where they were found."
     (goto-char (marker-position marker))
     (set-marker marker nil nil)))
 
-;; 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
+(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,6 +1051,23 @@ where they were found."
                           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,10 +1160,9 @@ where they were found."
       (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.
+  "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,7 +1192,7 @@ where they were found."
           (error "File %s not found" file))
       (set-buffer the-buffer))))
 
-(defun tag-find-file-of-tag (file)
+(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,9 +1200,10 @@ where they were found."
 
 ;; `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 ()
+  "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,7 +1238,7 @@ where they were found."
   ;; Use eq instead of = in case char-after returns nil.
   (eq (char-after (point-min)) ?\f))
 
-(defun etags-file-of-tag (&optional relative)
+(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,7 +1248,7 @@ where they were found."
                           (file-truename default-directory))))))
 
 
-(defun etags-tags-completion-table ()
+(defun etags-tags-completion-table () ; Doc string?
   (let ((table (make-vector 511 0))
         (progress-reporter
          (make-progress-reporter
@@ -1265,7 +1278,7 @@ where they were found."
                 table)))
     table))
 
-(defun etags-snarf-tag (&optional use-explicit)
+(defun etags-snarf-tag (&optional use-explicit) ; Doc string?
   (let (tag-text line startpos explicit-start)
     (if (save-excursion
           (forward-line -1)
@@ -1305,15 +1318,20 @@ where they were found."
     (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)
+  "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,7 +1380,7 @@ where they were found."
          (forward-char 1))
     (beginning-of-line)))
 
-(defun etags-list-tags (file)
+(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,7 +1453,7 @@ where they were found."
             (funcall ins-symb (car sy))))
         (sort-lines nil beg (point))))))
 
-(defun etags-tags-apropos (string)
+(defun etags-tags-apropos (string) ; Doc string?
   (when tags-apropos-verbose
     (princ "Tags in file `")
     (tags-with-face 'highlight (princ buffer-file-name))
@@ -1496,7 +1514,7 @@ where they were found."
     (message nil))
   (when tags-apropos-verbose (princ "\n")))
 
-(defun etags-tags-table-files ()
+(defun etags-tags-table-files () ; Doc string?
   (let ((files nil)
         beg)
     (goto-char (point-min))
@@ -1508,7 +1526,7 @@ where they were found."
           (setq files (cons (buffer-substring beg (1- (point))) files))))
     (nreverse files)))
 
-(defun etags-tags-included-tables ()
+(defun etags-tags-included-tables () ; Doc string?
   (let ((files nil)
         beg)
     (goto-char (point-min))
@@ -1524,9 +1542,10 @@ where they were found."
 
 ;; 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 ()
+  "Return 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,15 +1579,20 @@ where they were found."
 ;; 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)
+  "Return 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,6 +1601,8 @@ where they were found."
 ;; 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)
+  "Return 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,6 +1612,8 @@ where they were found."
 ;; 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)
+  "Return 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,6 +1625,8 @@ where they were found."
 ;; 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)
+  "Return 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,6 +1635,8 @@ where they were found."
 ;; 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)
+  "Return 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,6 +1644,9 @@ where they were found."
 ;; 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)
+  "Return 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,10 +1654,12 @@ where they were found."
 
 ;; t if point is in a tag line with a tag containing TAG as a substring.
 (defun tag-any-match-p (tag)
+  "Return 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)
+  "Return non-nil if current tag line matches regexp RE."
   (save-excursion
     (beginning-of-line)
     (let ((bol (point)))
@@ -1845,7 +1882,7 @@ See also the documentation of the variable `tags-file-name'."
         tags-loop-operate `(perform-replace ',from ',to t t ',delimited))
   (tags-loop-continue (or file-list-form t)))
 
-(defun tags-complete-tags-table-file (string predicate what)
+(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,7 +2003,7 @@ see the doc of that variable if you want to add names to the list."
   (set-buffer-modified-p nil)
   (select-tags-table-mode))
 
-(defvar select-tags-table-mode-map
+(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)