[Emacs-diffs] /srv/bzr/emacs/trunk r105025: Document some Info functions (Bug#1084).

[Chong Yidong]

------------------------------------------------------------
revno: 105025
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Thu 2011-07-07 16:35:28 -0400
message:
  Document some Info functions (Bug#1084).
  
  * lisp/info.el (info, Info-read-node-name-2, Info-read-node-name-1)
  (Info-read-node-name): Doc fix.
modified:
  lisp/ChangeLog
  lisp/info.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2011-07-07 18:31:57 +0000
+++ b/lisp/ChangeLog    2011-07-07 20:35:28 +0000
@@ -1,5 +1,8 @@
 2011-07-07  Chong Yidong  <address@hidden>
 
+       * info.el (info, Info-read-node-name-2, Info-read-node-name-1)
+       (Info-read-node-name): Doc fix (Bug#1084).
+
        * thingatpt.el (forward-thing, bounds-of-thing-at-point)
        (thing-at-point, beginning-of-thing, end-of-thing, in-string-p)
        (end-of-sexp, beginning-of-sexp)

=== modified file 'lisp/info.el'
--- a/lisp/info.el      2011-07-07 18:28:25 +0000
+++ b/lisp/info.el      2011-07-07 20:35:28 +0000
@@ -621,7 +621,7 @@
 Optional argument FILE-OR-NODE specifies the file to examine;
 the default is the top-level directory of Info.
 Called from a program, FILE-OR-NODE may specify an Info node of the form
-`(FILENAME)NODENAME'.
+\"(FILENAME)NODENAME\".
 Optional argument BUFFER specifies the Info buffer name;
 the default buffer name is *info*.  If BUFFER exists,
 just switch to BUFFER.  Otherwise, create a new buffer
@@ -1572,7 +1572,12 @@
 (defvar Info-read-node-completion-table)
 
 (defun Info-read-node-name-2 (dirs suffixes string pred action)
-  "Virtual completion table for file names input in Info node names."
+  "Internal function used to complete Info node names.
+Return a completion table for Info files---the FILENAME part of a
+node named \"(FILENAME)NODENAME\".  DIRS is a list of Info
+directories to search if FILENAME is not absolute; SUFFIXES is a
+list of valid filename suffixes for Info files.  See
+`try-completion' for a description of the remaining arguments."
   (setq suffixes (remove "" suffixes))
   (when (file-name-absolute-p string)
     (setq dirs (list (file-name-directory string))))
@@ -1602,10 +1607,9 @@
            (push (if string-dir (concat string-dir file) file) names)))))
     (complete-with-action action names string pred)))
 
-;; This function is used as the "completion table" while reading a node name.
-;; It does completion using the alist in Info-read-node-completion-table
-;; unless STRING starts with an open-paren.
 (defun Info-read-node-name-1 (string predicate code)
+  "Internal function used by `Info-read-node-name'.
+See `completing-read' for a description of arguments and usage."
   (cond
    ;; First complete embedded file names.
    ((string-match "\\`([^)]*\\'" string)
@@ -1618,7 +1622,6 @@
      (substring string 1)
      predicate
      code))
-
    ;; If a file name was given, then any node is fair game.
    ((string-match "\\`(" string)
     (cond
@@ -1630,9 +1633,10 @@
        code Info-read-node-completion-table string predicate))))
 
 ;; Arrange to highlight the proper letters in the completion list buffer.
-
-
 (defun Info-read-node-name (prompt)
+  "Read an Info node name with completion, prompting with PROMPT.
+A node name can have the form \"NODENAME\", referring to a node
+in the current Info file, or \"(FILENAME)NODENAME\"."
   (let* ((completion-ignore-case t)
         (Info-read-node-completion-table (Info-build-node-completions))
         (nodename (completing-read prompt 'Info-read-node-name-1 nil t)))