説明文字列を書くうえでのヒントや慣習を述べます。 コマンドM-x checkdoc-minor-modeを実行して、 これらの慣習の多くを確認できます。
説明文字列には、関数や変数の使い方の詳細を述べる追加の行があってよい。 それらの行も完全な文から成るべきであるが、見ためをよくするために 適当に詰めてよい。
しかし、説明文字列全体を単純に整形するよりは、 注意深く行分けすると読みやすくなる。 説明文字列が長い場合には、話題ごとに空行で区切る。
nil
以外の値はすべて同値であることを明らかにし、
nil
とnil
以外の意味を明確に示すこと。
/
の説明文字列では、
その第2引数の名前はdivisor
なので、‘DIVISOR’と表す。
また、リストやベクトルを(その一部が変化するかもしれない)構成部分に 分解したものを示すときなどのメタ変数には、すべて大文字を使う。
This function sets the variable `buffer-file-name'.
ハイパーリンクは、変数buffer-file-name
の説明文字列を指し、
その関数の説明文字列は指さない。
シンボルに関数定義や変数定義があっても、 説明文字列でのシンボルの使い方には無関係な場合には、 シンボルの名前のまえに単語‘symbol’を書けば、 ハイパーリンクを作らないようにできる。 たとえば、つぎのようにすると、
If the argument KIND-OF-RESULT is the symbol `list', this function returns a list of all the objects that satisfy the criterion.
ここではlist
の関数/変数定義は無関係なので、
関数list
の説明文字列を指すハイパーリンクは作られない。
forward-char
に現在バインドされているキーにEmacsが置き換える。
(普通は‘C-f’であるが、ユーザーがキーバインディングを変更していれば、
別の文字になる。)
see Keys in Documentation。
説明文字列の表示を遅くしてしまうので、 ‘\\[...]’を何回も使うのは実用的ではない。 したがって、読者のメジャーモードのもっとも重要なコマンドの記述にこれを使い、 モードのキーマップの残りを表示するには‘\\{...}’を使う。