GNU Emacs Lisp Reference Manual

21.2: Access to Documentation Strings

Function: documentation-property symbol property &optional verbatim

This function returns the documentation string that is recorded symbol's property list under property property. It retrieves the text from a file if necessary, and runs substitute-command-keys to substitute actual key bindings. (This substitution is not done if verbatim is non-nil; the verbatim argument exists only as of Emacs 19.)

(documentation-property 'command-line-processed
   'variable-documentation)
     => "t once command line has been processed"
(symbol-plist 'command-line-processed)
     => (variable-documentation 188902)

Function: documentation function &optional verbatim

This function returns the documentation string of function. It reads the text from a file if necessary. Then (unless verbatim is non-nil) it calls substitute-command-keys, to return a value containing the actual (current) key bindings.

The function documentation signals a void-function error if function has no function definition. However, it is ok if the function definition has no documentation string. In that case, documentation returns nil.

Here is an example of using the two functions, documentation and documentation-property, to display the documentation strings for several symbols in a *Help* buffer.

(defun describe-symbols (pattern)
  "Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the `*Help*' buffer."
  (interactive "sDescribe symbols matching: ")
  (let ((describe-func
         (function 
          (lambda (s)
            ;; Print description of symbol.
            (if (fboundp s)             ; It is a function.
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (commandp s) 
                       (let ((keys (where-is-internal s)))
                         (if keys
                             (concat
                              "Keys: "
                              (mapconcat 'key-description 
                                         keys " "))
                           "Keys: none"))
                     "Function")
                   (or (documentation s) 
                       "not documented"))))

            (if (boundp s)              ; It is a variable.
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (user-variable-p s) 
                       "Option " "Variable")
                   (or (documentation-property 
                         s 'variable-documentation)
                       "not documented")))))))
        sym-list)
    ;; Build a list of symbols that match pattern.
    (mapatoms (function 
               (lambda (sym)
                 (if (string-match pattern (symbol-name sym))
                     (setq sym-list (cons sym sym-list))))))
    ;; Display the data.
    (with-output-to-temp-buffer "*Help*"
      (mapcar describe-func (sort sym-list 'string<))
      (print-help-return-message))))

The describe-symbols function works like apropos, but provides more information.

(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option 
*Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
set-goal-column Command: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.
temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was
at the start of current run of vertical motion commands.
When the `track-eol' feature is doing its job, the value is 9999.
---------- Buffer: *Help* ----------

Function: Snarf-documentation filename

This function is used only during Emacs initialization, just before the runnable Emacs is dumped. It finds the file offsets of the documentation strings stored in the file filename, and records them in the in-core function definitions and variable property lists in place of the actual strings. See Building Emacs.

Emacs finds the file filename in the emacs/etc directory. When the dumped Emacs is later executed, the same file is found in the directory doc-directory. Usually filename is "DOC-version".

Variable: doc-directory

This variable holds the name of the directory which should contion the file "DOC-version" that contains documentation strings for built-in and preloaded functions and variables.

In most cases, this is the same as data-directory. They may be different when you run Emacs from the directory where you built it, without actually installing it. See data-directory in Help Functions.

In older Emacs versions, exec-directory was used for this.