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

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

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

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

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

  関数では最初の行は“その関数は何を行うのか?”、変数にたいしては最初の行は“その値は何を意味するのか?”という問いに簡略に答えること。

  ドキュメント文字列を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と同じではない。

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

• ドキュメント文字列の開始と終了に空白文字を使用しないこと。
• ソースコード内の後続行のテキスト、最初の行と揃うようにドキュメント文字列の後続行をインデントしてはならない。これはソースコードでは見栄えがよいがユーザーがドキュメトを閲覧する際は奇妙な見栄えになる。開始のダブルクォーテーションの前のインデントは文字列の一部には含まれないことを忘れないこと!
• ドキュメント文字列がLispシンボルを参照する際には、たとえば(‘..’)のように、それがプリントされるとき(通常は小文字を意味する)のように、前後をcurved single quoteで括って記述すること。例外が2つある。tとnilは前後の区切り記号を記述しない。たとえば:

   CODE can be ‘lambda’, nil, or t.
  

  curved single quoteを入力する方法についてはQuotation Marks in The GNU Emacs Manualを参照のこと。

  ドキュメント文字列は‘like-this’ではなく`like-this'のように、grave accent `とapostrophe 'でシンボルをクォートする古いシングルクォートの慣習も使用できる。この古い慣習はgrave accentとapostropheが鏡像となる今では時代遅れのディスプレイ用にデザインされている。この慣習を使用するドキュメントはhelpバッファーへコピー時にはユーザーが望む形式に変換される。Keys in Documentationを参照のこと。

  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'.
  

  最後にURLのハイパーリンクを作成するには‘URL’の後にURLをシングルクォートして記述する。たとえば、

  The home page for the GNU project has more information (see URL
  `https://www.gnu.org/').
  

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

  ドキュメント文字列の表示が低速になるので非常に多数回の‘\\[…]’の使用は実用的ではない。メジャーモードのもっとも重要なコマンドの記述にこれを使用して、そのモードの残りのキーマップの表示には‘\\{…}’を使用する。

• 一貫性を保つために関数のドキュメント文字列の最初のセンテンス内の動詞は、命令形で表すこと。たとえば“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.”、“in contrast to(対照的に)”に“c.f.”、“with respect to(に関しては)”にたいする“w.r.t.”のような略語の使用は可能なかぎり避けるよう努力すること。ほとんど常に展開されたバージョンのほうが読み易い²⁷。
• 特定のモードや状況でのみコマンドに意味がある際にはドキュメント文字列内でそれに言及すること。たとえばdired-find-fileのドキュメントは:

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

• ユーザーがセットしたいと望むかもしれないオプションを表す変数を定義する際にはdefcustomを使用すること。Defining Variablesを参照のこと。
• 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で編集する誰かをあなたが予期せぬのなら、この回避策は必要ない。