apropos.el doc fixes.

* lisp/apropos.el (apropos-do-all, apropos-library, apropos-value)
(apropos-documentation): Doc fixes.

2 files changed, 33 insertions, 8 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index fd403ee047..0b0e433c7c 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,8 @@
+2011-11-12  Glenn Morris  <[email protected]>
+
+	* apropos.el (apropos-do-all, apropos-library, apropos-value)
+	(apropos-documentation): Doc fixes.
+
 2011-11-11  Juanma Barranquero  <[email protected]>
 
 	* progmodes/idlw-shell.el (idlwave-shell-make-new-bp-overlay):
diff --git a/lisp/apropos.el b/lisp/apropos.el
index d3d66f2a07..1dfe5cde9e 100644
--- a/lisp/apropos.el
+++ b/lisp/apropos.el
@@ -66,9 +66,22 @@
 
 ;; I see a degradation of maybe 10-20% only.
 (defcustom apropos-do-all nil
-  "Whether the apropos commands should do more.
-
-Slows them down more or less.  Set this non-nil if you have a fast machine."
+  "Non nil means apropos commands will search more extensively.
+This may be slower.  This option affects the following commands:
+
+`apropos-variable' will search all variables, not just user variables.
+`apropos-command' will also search non-interactive functions.
+`apropos' will search all symbols, not just functions, variables, faces,
+and those with property lists.
+`apropos-value' will also search in property lists and functions.
+`apropos-documentation' will search all documentation strings, not just
+those in the etc/DOC documentation file.
+
+This option only controls the default behavior.  Each of the above
+commands also has an optional argument to request a more extensive search.
+
+Additionally, this option makes the function `apropos-library'
+include key-binding information in its output."
   :group 'apropos
   :type 'boolean)
 
@@ -582,7 +595,8 @@ Returns list of symbols and documentation found."
 (defun apropos-library (file)
   "List the variables and functions defined by library FILE.
 FILE should be one of the libraries currently loaded and should
-thus be found in `load-history'."
+thus be found in `load-history'.  If `apropos-do-all' is non-nil,
+the output includes key-bindings of commands."
   (interactive
    (let* ((libs (delq nil (mapcar 'car load-history)))
           (libs
@@ -693,7 +707,9 @@ search for matches for that word as a substring.  If it is a list of words,
 search for matches for any two (or more) of those words.
 
 With \\[universal-argument] prefix, or if `apropos-do-all' is non-nil, also looks
-at the function and at the names and values of properties.
+at function definitions (arguments, documentation and body) and at the
+names and values of properties.
+
 Returns list of symbols and values found."
   (interactive (list (apropos-read-pattern "value")
 		     current-prefix-arg))
@@ -738,10 +754,14 @@ or a regexp (using some regexp special characters).  If it is a word,
 search for matches for that word as a substring.  If it is a list of words,
 search for matches for any two (or more) of those words.
 
-With \\[universal-argument] prefix, or if `apropos-do-all' is non-nil, also use
-documentation that is not stored in the documentation file and show key
-bindings.
+Note that by default this command only searches in the file specified by
+`internal-doc-file-name'; i.e., the etc/DOC file.  With \\[universal-argument] prefix,
+or if `apropos-do-all' is non-nil, it searches all currently defined
+documentation strings.
+
 Returns list of symbols and documentation found."
+  ;; The doc used to say that DO-ALL includes key-bindings info in the
+  ;; output, but I cannot see that that is true.
   (interactive (list (apropos-read-pattern "documentation")
 		     current-prefix-arg))
   (apropos-parse-pattern pattern)