この関数はプロパティproperty配下のsymbolのプロパティリスト内に記録されたドキュメント文字列をリターンする。これはほとんどの場合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がnilなら、この関数はsubstitute-command-keysを呼び出す。結果はリターンするための文字列。
documentation関数はfunctionが関数定義をもたなければvoid-functionエラーをシグナルする。しかし関数定義がドキュメントをもたない場合は問題ない。その場合はdocumentationはnilをリターンする。
documentationが関数オブジェクトから生のdoc文字列を抽出するために用いるジェネリック関数。対応するメソッドを追加することによって、特定の関数タイプのdoc文字列を取得する方法を指定できる。
この関数はfaceのドキュメント文字列をフェイスとしてリターンする。
以下は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)
;; シンボルの説明をプリントする (if (fboundp s) ; これは関数 (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) ; これは変数
(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)
;; パターンにマッチするシンボルのリストを構築
(mapatoms (lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list)))))
;; データを表示
(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’. msgid "" "(defun describe-symbols (pattern)\n" " \"Describe the Emacs Lisp symbols matching PATTERN.\n" "All symbols that have PATTERN in their name are described\n" "in the `*Help*' buffer.\"\n" " (interactive \"sDescribe symbols matching: \")\n" " (let ((describe-func\n" " (function\n" " (lambda (s)\n"
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ではなくEmacsをビルドしたディレクトリーからEmacsを実行したときは異なるかもしれない。Definition of data-directoryを参照のこと。