この関数は、symbol のプロパティリストのプロパティ property に記録されているドキュメント文字列を返します。主に、property が variable-documentation
である変数のドキュメント文字列を参照する際に使用されます。ただし、カスタマイズグループなど、他の種類のドキュメントを参照する場合にも使用できます（ただし、関数のドキュメントについては、後述の
documentation 関数を使用してください）。
プロパティの値が DOC ファイルまたはバイトコンパイル済みファイルに格納されているドキュメント文字列を指す場合、この関数はその文字列を検索して返します。
プロパティの値が nil
ではなく、文字列でもなく、またファイル内のテキストを参照するものでもない場合、それは Lisp 式として評価され、文字列が得られます。
最後に、この関数は文字列を substitute-command-keys
に通してキーバインドを置換します（ドキュメントにおけるキーバインドの置換を参照）。verbatim が nil
以外の場合は、このステップをスキップします。
(documentation-property 'command-line-processed
'variable-documentation)
⇒ "Non-nil once command line has been processed"
(symbol-plist 'command-line-processed)
⇒ (variable-documentation 188902)
(documentation-property 'emacs 'group-documentation)
⇒ "Customization of the One True Editor."
この関数は、function のドキュメント文字列を返します。通常の関数だけでなく、マクロ、名前付きキーボードマクロ、特殊フォームも処理します。
function がシンボルの場合、この関数はまずそのシンボルの function-documentation プロパティを確認します。そこに nil 以外の値が設定されていれば、その値からドキュメントが取得されます（値が文字列でない場合は評価されます）。
function がシンボルでない場合、あるいは function-documentation プロパティを持たない場合、documentation
は実際の関数定義からドキュメント文字列を抽出し、呼び出された際にはファイルからそれを読み込みます。
最後に、verbatim が non-nil
でない限り、この関数は substitute-command-keys
を呼び出します。その結果が、返すドキュメント文字列となります。
documentation 関数は、function
に関数定義がない場合に void-function
エラーを通知します。ただし、関数定義にドキュメント文字列がなくても問題ありません。その場合、documentation は nil を返します。
documentation
が関数オブジェクトから生のドキュメント文字列を抽出する際に使用する汎用関数です。特定の関数型のドキュメント文字列の取得方法は、対応するメソッドを追加することで指定できます。
この関数は、face のドキュメント文字列をフェイスとして返します。
ここでは、2つの関数 documentation と documentation-property を使用して、*Help* バッファ内の複数のシンボルのドキュメント文字列を表示する例を示します。
(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
(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 (custom-variable-p s)
"Option " "Variable")
(or (documentation-property
s 'variable-documentation)
"not documented"))))))
sym-list)
;; Build a list of symbols that match pattern.
(mapatoms (lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list)))))
;; Display the data.
(help-setup-xref (list 'describe-symbols pattern)
(called-interactively-p 'interactive))
(with-help-window (help-buffer)
(mapcar describe-func (sort sym-list)))))
describe-symbols 関数は apropos と同様に動作しますが、より多くの情報を提供します。
(describe-symbols "goal") ---------- Buffer: *Help* ---------- goal-column Option Semipermanent goal column for vertical motion, as set by ...
minibuffer-temporary-goal-position Variable not documented
set-goal-column Keys: 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 ARG, 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'. (fn ARG)
temporary-goal-column Variable Current goal column for vertical motion. It is the column where point was at the start of the current run of vertical motion commands. When moving by visual lines via the function `line-move-visual', it is a cons cell (COL . HSCROLL), where COL is the x-position, in pixels, divided by the default column width, and HSCROLL is the number of columns by which window is scrolled from left margin. When the `track-eol' feature is doing its job, the value is `most-positive-fixnum'. ---------- Buffer: *Help* ----------
この関数は、Emacsのビルド時に、実行可能なEmacsがダンプされる直前に使用されます。ファイル filename に格納されているドキュメント文字列の位置を特定し、それらの位置を関数定義や変数のプロパティリストのメモリ上に記録します。Emacsのビルドを参照してください。
Emacsはemacs/etcディレクトリからファイルfilenameを読み込みます。ダンプされたEmacsを後で実行すると、同じファイルがdoc-directoryディレクトリ内で検索されます。通常、filenameは"DOC"となります。
この変数には、組み込み関数や変数のドキュメント文字列を含むファイル "DOC"
が格納されるべきディレクトリ名が保持されます。
ほとんどの場合、これは data-directory
と同じです。実際にインストールせず、ビルドしたディレクトリから Emacs を起動した場合には、異なる場合があります。data-directory
の定義を参照してください。