---

D.6 ドキュメント文字列のヒント

以下はドキュメント文字列記述に関するいくつかのヒントと慣習です。コマンドM-x checkdoc-minor-modeを実行すれば慣習の多くをチェックできます。

• ユーザーが理解することを意図したすべての関数、コマン、変数はドキュント文字列をもつこと。
• Lispプログラムの内部的な変数とサブルーチンは同様にドキュメント文字列をもつことができる。ドキュメント文字列は実行中のEmacs内で非常に僅かなスペースしか占めない。
• 80列スクリーンのEmacsウィンドウに適合するようにドキュメント文字列をフォーマットすること。ほとんどの行を60文字以下に短くするのは良いアイデアである。最初の行は74文字以下にすること。さもないとaproposの出力で見栄えが悪くなる。

  見栄えがよくなるならそのテキストをフィルできる。Emacs Lispモードはemacs-lisp-docstring-fill-columnで指定された幅にドキュメント文字列をフィルする。しかしドキュメント文字列の行ブレークを注意深く調整すればドキュメント文字列の可読性をより向上できることがある。ドキュメント文字列が長い場合にはセクション間に空行を使用すること。

• ドキュンメント文字列の最初の行は、それ自身が要約となるような1つか2つの完全なセンテンスから成り立つこと。M-x aproposは最初の行だけを表示するので、その行のコンテンツ単独で完結していなければ結果の見栄えは悪くなる。特に最初の行は大文字で始めてピリオドで終わること。

  関数では“これは何を行う関数か?”、変数では“これは何を意味する変数か?”という問いにたいして1行目で簡潔に答える必要がある。これらの問いにたいしてその関数や変数のユーザーや呼び出し元が理解できる方法で答えるのが望ましい。特に関数のコードの動作を列挙して何を行なうかを示すのではなく、それらの動作の役割りと関数の責任について説明すること。

  ドキュメント文字列を1行に制限しないこと。その関数や変数の使用法の詳細を説明する必要に応じてその分の行数を使用すること。テキストの残りの部分にたいしても完全なセンテンスを使用してほしい。

• ユーザーが無効化されたコマンドの使用を試みる際には、Emacsはそれのドキュメント文字列の最初のパラグラフ(最初の空行までのすべて)だけを表示する。もし望むなら、その表示をより有用になるように最初の空行の前に何の情報を含めるか選択できる。
• 最初の行ではその関数のすべての重要な引数(特に必須な引数)と、関数呼び出しで記述される順にそれらに言及すること。その関数が多くの引数をもつなら最初の行でそれらすべてに言及するのは不可能である。この場合にはもっとも重要な引数を含む最初の引数数個について最初の行で言及すること。
• ある関数のドキュメント文字列がその関数の引数の値に言及する際には、引数を大文字にした名前が引数の値であるかのように使用すること。つまり関数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 ...
  

• ドキュメント文字列内でLispシンボルに言及する際にはcase(大文字小文字)を絶対に変更しないこと。そのシンボルの名前がfooなら“Foo”ではなく“foo”(“Foo”は違うシンボル)。

  これは関数の引数の値の記述ポリシーと反するように見えるかもしれないが矛盾は実際には存在しない。引数のvalueはその関数が値の保持に使用するsymbolと同じではない。

  これによりセンテンス先頭に小文字を置くことになり、それが煩しいならセンテンス開始がシンボルにならないようにセンテンスを書き換えること。

• ドキュメント文字列の開始と終了に空白文字を使用しないこと。
• ソースコード内の後続行のテキスト、最初の行と揃うようにドキュメント文字列の後続行をインデントしてはならない。これはソースコードでは見栄えがよいがユーザーがドキュメトを閲覧する際は奇妙な見栄えになる。開始のダブルクォーテーションの前のインデントは文字列の一部には含まれないことを忘れないこと!
• ドキュメントにおいてASCIIのアポストロフィやグレイブアクセントを表示する必要がある際には、ドキュメントの文字列リテラルに‘\\='’や‘\\=`’を使えば文字はそのまま表示される。
• ドキュメント文字列ではLispシンボルではないような式はそれら自身を表しているかもしれないのでクォートしてはならない。たとえば‘Return the list `(NAME TYPE RANGE)' ...’や‘Return the list \\='(NAME TYPE RANGE) ...’ではなく‘Return the list (NAME TYPE RANGE) ...’と記述すること。
• ドキュメント文字列がLispシンボルを参照する際には、それがプリントされるとき(通常は小文字を意味する)のように前にグレイブアクセント‘`’、後にアポストロフィー‘'’を記述すること。例外が2つある。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/').
  

• ドキュメント文字列内に直接キーシーケンスを記述しないこと。かわりに、それらを表すために‘\\[…]’構文を使用すること。たとえば‘C-f’と記述するかわりに‘\\[forward-char]’と記述する。Emacsがドキュメント文字列を表示する際には何であれカレントでforward-charにバインドされたキーに置き換える(これは通常は‘C-f’だがユーザーがキーバインディングを変更していれば何か他の文字かもしれない)。ドキュメント内でのキーバインディングの置き換えを参照のこと。
• メジャーモードのドキュメント文字列ではグローバルマップではなく、そのモードのローカルマップを参照したいだろう。したがってどのキーマップを使用するか指定するために、ドキュメント文字列内で一度‘\\<…>’構文を使用する。最初に‘\\[…]’を使用する前、センテンスの途中以外でこれを行うこと(マップがロードされていないと、マップへの参照はまだマップが定義されていないことを示すセンテンスに置き換えられるだろう)。‘\\<…>’の内部のテキストはメジャーモードにたいするローカルキーマップを含む変数名であること。

  ‘\\[…]’を使用するたびに、僅かだがドキュメント文字列の表示が低速になる。これらを大量に使用すると僅かな低速化が積み重なり、特に低速なシステムでは有意なものとなるかもしれない。したがってこれらの過度な使用は推奨しない(同一ドキュメント内で同じコマンドへの複数参照の使用を避けるよう試みる等)。

• 一貫性を保つために関数のドキュメント文字列の最初のセンテンス内の動詞は、命令形で表すこと。たとえば“Return the cons of A and B.”、好みによっては“Returns the cons of A and B.”を使用する。通常は最初のパラグラフの残りの部分にたいして同様に行っても見栄えがよい。各センテンスが叙実的で適切な主題をもつなら後続のパラグラフの見栄えはよくなる。
• yes-or-no述語であるような関数のドキュメント文字列は、何が真を構成するか明示的に示すために、“Return t if”のような単語で始まること。単語“return”は小文字の“t”で開始される幾分紛らわしい可能性のあるセンテンスを避ける。
• ドキュメント文字列は受動態ではなく能動態、未来形ではなく現在形で記述すること。たとえば“A list containing A and B will be returned.”ではなく、“Return a list containing A and B.”と記述すること。
• 不必要な“cause”(や同等の単語)の使用を避けること。“Cause Emacs to display text in boldface”ではなく、単に“Display text in boldface”と記述すること。
• 多くの人にとってなじみがなくtypoと間違えるであろうから、“iff”(“if and only if”を意味する数学用語)の使用を避けること。ほとんどの場合には、その意味は単なる“if”で明快である。それ以外ではその意味を伝える代替えフレーズを探すよう試みること。
• “for example(たとえば)”に“e.g.”、“that is(つまり)”に“i.e.”、“number(数値)”に“no.”、“compare(比較)”/“see also(参照)”に“cf.”、“with respect to(に関しては)”にたいする“w.r.t.”のような略語の使用は可能なかぎり避けるよう努力すること。ほとんど常に展開されたバージョンのほうが読み易い³⁶。
• 特定のモードや状況でのみコマンドに意味がある際にはドキュメント文字列内でそれに言及すること。たとえばdired-find-fileのドキュメントは:

  In Dired, visit the file or directory named on this line.
  

• ユーザーがセットしたいと望むかもしれないオプションを表す変数を定義する際にはdefcustomを使用すること。グローバル変数の定義を参照のこと。
• yes-or-noフラグであるような変数のドキュメント文字列は、すべての非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で編集する誰かをあなたが予期せぬのなら、この回避策は必要ない。