Emacsでは、さまざまなグループ分けに基づいて関数を一覧表示できます。例えば、string-trimとmapconcatは「文字列」関数であるため、M-x shortdoc RET
string RETではこれらや、文字列を操作するその他の関数の概要が表示されます。
ドキュメントグループは define-short-documentation-group
マクロで作成します。優れたドキュメントグループの書き方については、ドキュメントグループのヒントを参照してください。
group を関数群として定義し、それらの関数の使用方法について簡潔な説明を記載してください。オプション引数 functions は、要素が以下の形式であるリストです：
(func [keyword val]...)
以下のキーワードが認識されます：
:eval値は、評価時に副作用のないフォームである必要があります。このフォームは、ドキュメント内で prin1
を用いて出力されます（出力関数を参照）。ただし、フォームが文字列である場合はそのまま挿入され、その文字列が
read
となることでフォームが生成されます。いずれの場合も、その後フォームが評価され、その結果が使用されます。例えば：
:eval (concat "foo" "bar" "zot") :eval "(make-string 5 ?x)"
以下の結果となります：
(concat "foo" "bar" "zot") ⇒ "foobarzot" (make-string 5 ?x) ⇒ "xxxxx"
（ここでLispのフォームと文字列の両方を許容しているのは、フォームの特定の表現が望ましいごく少数のケースにおいて、出力を制御できるようにするためである。例では、‘?x’が文字列に含まれていなければ、‘120’として出力されていただろう。）
:no-evalこれは :eval と同様ですが、フォームは評価されません。このような場合は、何らかの :result 要素（後述）を含める必要があります。
:no-eval (file-symlink-p "/tmp/foo") :eg-result t
:no-eval*:no-evalと同様ですが、結果として常に‘[it depends]’が挿入されます。例えば：
:no-eval* (buffer-string)
以下の結果となります：
(buffer-string) → [it depends]
:no-value:no-evalと同様ですが、対象の関数に明確に定義された戻り値がなく、副作用のみを目的として使用される場合に用いられます。
:result評価を行わない例形式の結果を出力するために使用されていた。
:no-eval (setcar list 'c) :result c
:eg-result評価を行わない例形式から、サンプル結果を出力するために使用されていました。例えば：
:no-eval (looking-at "f[0-9]") :eg-result t
以下の結果となります：
(looking-at "f[0-9]") eg. → t
:result-string:eg-result-stringこれら2つはそれぞれ :result および :eg-result
と同じですが、そのまま挿入されます。これは、結果が判読不能な場合や、特定の形式にする必要がある場合に有用です：
:no-eval (find-file "/tmp/foo") :eg-result-string "#<buffer foo>" :no-eval (default-file-modes) :eg-result-string "#o755"
:no-manualこの関数がマニュアルに記載されていないことを示します。
:argsデフォルトでは、関数の実際の引数リストが表示されます。:args
がある場合は、代わりにそれが使用されます。
:args (regexp string)
ごく簡単な例を挙げます：
(define-short-documentation-group string "Creating Strings" (substring :eval (substring "foobar" 0 3) :eval (substring "foobar" 3)) (concat :eval (concat "foo" "bar" "zot")))
第1引数は定義対象のグループ名であり、その後に任意の数の関数記述が続きます。
関数は、任意の数のドキュメントグループに属することができます。
機能説明に加えて、リストには文字列要素を含めることもでき、これを用いてドキュメントグループをセクションごとに分割できます。
Lispパッケージでは、この関数を用いてグループに関数を追加できます。各elemは、前述の通り関数の説明である必要があります。groupは関数グループ、sectionは関数グループ内のどのセクションに関数を挿入するかを指定します。
group が存在しない場合は、作成されます。section が存在しない場合は、関数グループの末尾に追加されます。
shortdocグループで定義された関数の使用例をクエリすることもできます。
この関数は、function に関するすべての shortdoc
例を返します。戻り値はアリストであり、各要素は (group . examples)
という形式をしています。ここで、group は function が含まれるドキュメントグループであり、examples は group で定義された function の例を含む文字列です。
shortdoc-function-examples は、function が関数でない場合、または shortdoc の例がない場合に nil を返します。
この関数は、登録されている shortdoc グループを照会し、指定された Emacs Lisp function の使用例を現在のバッファに挿入します。help-fns-describe-function-functions
フックに追加するのに適しており、その場合、関数のドキュメントが要求された際に、shortdoc にある関数の使用例が *Help* バッファに表示されます。