Next: コメント記述のヒント, Previous: コンパイラー警告を回避するためのヒント, Up: ヒントと規約 [Contents][Index]
以下はドキュメント文字列記述に関するいくつかのヒントと慣習です。コマンドM-x checkdoc-minor-modeを実行すれば慣習の多くをチェックできます。
apropos
の出力で見栄えが悪くなる。
見栄えがよくなるならそのテキストをフィルできる。Emacs
Lispモードはemacs-lisp-docstring-fill-column
で指定された幅にドキュメント文字列をフィルする。しかしドキュメント文字列の行ブレークを注意深く調整すればドキュメント文字列の可読性をより向上できることがある。ドキュメント文字列が長い場合にはセクション間に空行を使用すること。
For a function, the first line should briefly answer the question, “What does this function do?” For a variable, the first line should briefly answer the question, “What does this value mean?” Prefer to answer these questions in a way that will make sense to users and callers of the function or the variable. In particular, do not tell what the function does by enumerating the actions of its code; instead, describe the role of these actions and the function’s contract.
ドキュメント文字列を1行に制限しないこと。その関数や変数の使用法の詳細を説明する必要に応じてその分の行数を使用すること。テキストの残りの部分にたいしても完全なセンテンスを使用してほしい。
eval
のドキュメント文字列では最初の引数の名前がform
なので‘FORM’で参照する:
Evaluate FORM and return its value.
同様にリストやベクターのサブユニットへの分解で、それらのいくつかを異なるように示すような際にはメタ構文変数(metasyntactic variables)を大文字で記述すること。以下の例の‘KEY’と‘VALUE’はこれの実践例:
The argument TABLE should be an alist whose elements have the form (KEY . VALUE). Here, KEY is ...
foo
なら“Foo”ではなく“foo”(“Foo”は違うシンボル)。
これは関数の引数の値の記述ポリシーと反するように見えるかもしれないが矛盾は実際には存在しない。引数のvalueはその関数が値の保持に使用するsymbolと同じではない。
これによりセンテンス先頭に小文字を置くことになり、それが煩しいならセンテンス開始がシンボルにならないようにセンテンスを書き換えること。
t
とnil
は前後の区切り記号を記述しない。たとえば:
CODE can be `lambda', nil, or t.
これらのドキュメント文字列をEmacsが表示する際には、文字の表示がサポートされていれば通常は‘`’ (グレイブアクセント)に‘‘’ (左シングルクォーテーションマーク)、‘'’ (アポストロフィー)に‘’’ (右シングルクォーテーションマーク)を表示することに注意。ドキュメント内でのキーバインディングの置き換えを参照のこと。 (このセクションの以前のバージョンでは、doc文字列で非ASCIIのシングルクォーテーションマークを推奨するバージョンがありましたが、このような文字をサポートしない端末におけるヘルプ文字列の表示が破壊されるので現在は推奨されていません。)
Helpモードはシングルクォートされたシンボル名がドキュメント文字列で使用されている際には、それが関数と変数のいずれかの定義をもっていれば自動的にハイパーリンクを作成する。これらの機能を使用するために何か特別なことを行う必要はない。しかしあるシンボルが関数と変数の両方の定義をもち一方だけを参照したい場合には、そのシンボル名の直前に‘variable’、‘option’、‘function’、‘command’の単語のいずれかを記述してそれを指定できる(これらの指示語の識別では大文字小文字に差はない)。たとえば以下を記述すると
This function sets the variable `buffer-file-name'.
これのハイパーリンクはbuffer-file-name
の変数のドキュメントだけを参照して関数のドキュメントは参照しない。
あるシンボルが関数および/または変数の定義をもつがドキュメントしているシンボルの使用とそれらが無関係なら、すべてのハイパーリンク作成を防ぐためにシンボル名の前に単語‘symbol’か‘program’を記述できる。たとえば、
If the argument KIND-OF-RESULT is the symbol `list', this function returns a list of all the objects that satisfy the criterion.
これは無関係な関数list
のドキュメントにハイパーリンクを作成しない。
変数ドキュメントがない変数には、通常はハイパーリンクは作成されない。そのような変数の前に単語‘variable’と‘option’のいずれかを記述すればハイパーリンクの作成を強制できる。
フェイスにたいするハイパーリンクはフェイスの前か後に単語‘face’があれば作成される。この場合にはたとえそのシンボルが変数や関数として定義されていてもフェイスのドキュメントだけが表示される。
Infoドキュメントにハイパーリンクを作成するには、‘info node’、‘Info node’、‘info anchor’、‘Info anchor’のいずれかの後Infoのノード(かアンカー)をシングルクォートして記述する。Infoファイル名のデフォルトは‘emacs’。たとえば、
See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
manページにハイパーリンクを作成するには‘Man page’,‘man page’、‘man page for’のいずれかの後にシングルクォートされた名前記述する。たとえば、
See the man page `chmod(1)' for details.
manページInfoドキュメントのほうが常に好ましいので、リンク可能なInfoマニュアルがあるならリンクすること。たとえばchmod
はGNU
Coreutilsマニュアルにドキュメントされているので、manページよりそれにリンクするほうがよい。
カスタマイゼーショングループをリンクするには、‘customization group’を前置してシングルクォートしたグループ名を記述する(各単語の先頭文字のcaseは区別しない)。たとえば、
See the customization group `whitespace' for details.
最後にURLのハイパーリンクを作成するには‘URL’の後にURLをシングルクォートして記述する。たとえば、
The GNU project website has more information (see URL `https://www.gnu.org/').
forward-char
にバインドされたキーに置き換える(これは通常は‘C-f’だがユーザーがキーバインディングを変更していれば何か他の文字かもしれない)。ドキュメント内でのキーバインディングの置き換えを参照のこと。
‘\\[…]’を使用するたびに、僅かだがドキュメント文字列の表示が低速になる。これらを大量に使用すると僅かな低速化が積み重なり、特に低速なシステムでは有意なものとなるかもしれない。したがってこれらの過度な使用は推奨しない(同一ドキュメント内で同じコマンドへの複数参照の使用を避けるよう試みる等)。
dired-find-file
のドキュメントは:
In Dired, visit the file or directory named on this line.
defcustom
を使用すること。グローバル変数の定義を参照のこと。
nil
値が等価であることを明確にして、nil
と非nil
が何を意味するかを明示的に示すために“Non-nil
means”のような単語で始めること。
The argument FOO can be either a number \(a buffer position) or a string (a file name).
これは‘(’をdefunの開始として扱う27.1より古いバージョンのEmacsでのバグを回避する(Defuns in The GNU Emacs Manualを参照)。コードを古いバージョンのEmacsで編集する誰かをあなたが予期せぬのなら、この回避策は必要ない。
Next: コメント記述のヒント, Previous: コンパイラー警告を回避するためのヒント, Up: ヒントと規約 [Contents][Index]