次へ: ドキュメントグループに関するヒント, 前へ: コンパイラ警告を回避するためのヒント, 上へ: ヒントと規約   [目次][索引]

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

ドキュメント文字列の記述に関するヒントと規約をいくつか紹介します。これらの規約の多くは、コマンド M-x checkdoc-minor-mode を実行することで確認できます。

• ユーザーが把握しておくべきすべてのコマンド、関数、または変数には、ドキュメント文字列を設けるべきです。
• Lispプログラムの内部変数やサブルーチンにも、ドキュメント文字列を持たせてもよいでしょう。実行中のEmacsにおいて、ドキュメント文字列が占有する領域はごくわずかです。
• ドキュメント文字列は、80列の画面のEmacsウィンドウに収まるようにフォーマットしてください。ほとんどの行は60文字以内に収めるのが望ましいです。1行目は74文字以内に収めてください。そうしないと、aproposの出力時に見栄えが悪くなります。

  これで問題なければ、テキストを入力してください。Emacs Lispモードでは、ドキュメント文字列はemacs-lisp-docstring-fill-columnで指定された幅に合わせて折り返されます。ただし、改行を慎重に調整することで、ドキュメント文字列の可読性を大幅に向上できる場合があります。ドキュメント文字列が長い場合は、セクション間に空行を入れてください。

• ドキュメント文字列の1行目は、それ自体で要約として成立する1〜2文の完全な文章で構成する必要があります。M-x apropos は1行目のみを表示するため、その行の内容が単独で成立していない場合、見栄えが悪くなります。特に、1行目は大文字で始め、ピリオドで終えるようにしてください。

  関数の場合、1行目で「この関数は何をするものか？」という問いに簡潔に答えるべきです。変数の場合、1行目で「この値は何を意味しているか？」という問いに簡潔に答えるべきです。これらの問いには、関数や変数の利用者や呼び出し手にとって分かりやすい形で答えるようにしてください。特に、コード内の処理を列挙して関数の動作を説明することは行わないでください。代わりに、それらの処理の役割と、関数の契約について説明してください。

  ドキュメント文字列を1行に限定せず、関数や変数の使い方の詳細を説明するために必要な行数を適宜使ってください。また、それ以外の箇所についても、完全な文章で記述してください。

• ユーザーが無効なコマンドを使用しようとすると、Emacsはドキュメント文字列の最初の段落――最初の空行までのすべて――のみを表示します。必要に応じて、最初の空行より前に表示する情報を選択することで、この表示を使いやすくすることができます。
• 1行目には、関数の重要な引数（特に必須引数）をすべて記載し、関数呼び出し時の記述順に従って並べる必要があります。関数の引数数が多い場合、1行目にすべてを記載することは現実的ではありません。その場合は、最も重要な引数を含む、最初の数個の引数を1行目に記載してください。
• 関数のドキュメント文字列で引数の値に言及する場合、その引数名をあたかもその値の名称であるかのように大文字で表記します。したがって、関数 eval のドキュメント文字列では、実際の引数名が form であるため、第1引数を ‘FORM’ と表記します：

  Evaluate FORM and return its value.
  

  また、リストやベクトルを、一部が可変となり得るサブユニットに分解して示す場合など、メタ構文変数は大文字で記述してください。以下の例における ‘KEY’ および ‘VALUE’ がこの慣例を示しています：

  The argument TABLE should be an alist whose elements
  have the form (KEY . VALUE).  Here, KEY is ...
  

• doc string で Lisp シンボルに言及する際は、大文字・小文字を変更しないでください。シンボル名が foo の場合は、“Foo” ではなく “foo” と記述してください（後者は別のシンボルになります）。

  これは、関数の引数に値を渡すという方針と矛盾するように見えるかもしれませんが、実際には矛盾はありません。引数の値は、関数が値を保持するために使用するシンボルとは異なるものです。

  これで文頭に小文字が来てしまい、それが気になる場合は、記号が文頭に来ないように文を書き直してください。

• ドキュメント文字列の先頭や末尾に空白文字を使用しないでください。
• ドキュメント文字列の後続行をインデントしないでください。そうすると、ソースコード上でテキストが1行目のテキストと揃ってしまいます。ソースコード上では見栄えが良いですが、ユーザーがドキュメントを表示した際には不自然に見えます。開始ダブルクォート前のインデントは、文字列の一部ではないことに注意してください！
• ドキュメント内で 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がこれらのドキュメント文字列を表示する際、表示機能がこれらの文字をサポートしていれば、通常 ‘`’（グレイヴ・アクセント）は ‘‘’（左シングルクォート）として、‘'’（アポストロフィ）は ‘’’（右シングルクォート）として表示されます。ドキュメント内でのキーバインドの置換を参照してください。（本セクションの以前のバージョンの一部では、ドキュメント文字列内で非ASCIIのシングルクォートを直接使用することが推奨されていましたが、これらの文字の表示をサポートしていないターミナルではヘルプ文字列の表示が崩れるため、現在は推奨されていません。）

  ヘルプモードでは、ドキュメント文字列内でシングルクォートで囲まれたシンボル名が使用されており、かつそのシンボルに関数または変数の定義のいずれかがある場合、自動的にハイパーリンクが作成されます。この機能を利用するために、特別な操作を行う必要はありません。ただし、シンボルに関数定義と変数定義の両方があり、そのうち一方のみを参照したい場合は、シンボル名の直前に ‘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 のドキュメント（ここでは無関係）へのハイパーリンクは作成しません。

  あるいは、記号の前に ‘\\+’ を付けることで、ハイパーリンクとしてマークされるのを防ぐこともできます。例：

  If the value of KIND-OF-RESULT is \\+`list',
  this function returns a list of all the objects
  that satisfy the criterion.
  

  通常、変数のドキュメントがない変数にはハイパーリンクが作成されません。このような変数に強制的にハイパーリンクを作成するには、変数の前に ‘variable’ または ‘option’ のいずれかの単語を記述してください。

  顔へのハイパーリンクは、顔名の前後に ‘face’ という単語がある場合にのみ作成されます。その場合、たとえその記号が変数や関数として定義されていても、顔のドキュメントのみが表示されます。

  Infoドキュメントへのハイパーリンクを作成するには、Infoノード（またはアンカー）の名前をシングルクォートで囲み、その前に ‘info node’、‘Info node’、‘info anchor’、または ‘Info anchor’ を記述します。Infoファイル名のデフォルトは ‘emacs’ です。例えば、

  See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
  

  manページへのハイパーリンクを作成するには、manページ名をシングルクォートで囲み、その前に ‘Man page’、‘man page’、または ‘man page for’ を記述します。例えば、

  See the man page `chmod(1)' for details.
  

  Infoドキュメントは常にmanページよりも好ましいため、利用可能な場合は必ずInfoマニュアルへのリンクを貼ってください。例えば、chmodはGNU Coreutilsマニュアルに記載されているため、manページではなくそちらへリンクを貼る方が適切です。

  カスタマイズグループにリンクするには、グループ名をシングルクォートで囲み、その前に ‘customization group’ を記述します（各単語の先頭文字は大文字・小文字を区別しません）。例えば、

  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’ ですが、ユーザーがキーバインドを変更している場合は、別の文字になることがあります。）ドキュメントにおけるキーバインドの置換を参照してください。
• メジャーモードのドキュメント文字列では、そのモードのグローバルマップではなく、ローカルマップのキーバインドを参照する必要があります。そのため、ドキュメント文字列内で一度だけ「\\<…>」という構文を使用し、どのキーマップを使用するかを指定してください。これは「\\[…]」を初めて使用する前に行い、文の途中で行わないでください（マップがロードされていない場合、マップへの参照が、「マップが現在定義されていない」という内容の文に置き換えられてしまうためです）。「\\<…>」の中のテキストには、メジャーモードのローカルキーマップを保持する変数名を記述してください。

  ‘\\[…]’ を使用するたびに、ドキュメント文字列の表示速度がわずかに低下します。これを多用すると、こうしたわずかな遅延が積み重なり、特に処理速度の遅いシステムでは顕著に現れる可能性があります。そのため、使いすぎないことを推奨します。例えば、同一のドキュメント文字列内で、同じコマンドへの参照を複数回使用することは避けるようにしてください。

• 一貫性を保つため、関数のドキュメント文字列の最初の文では、動詞を命令形で記述してください。例えば、「Returns the cons of A and B.」ではなく「Return the cons of A and B.」とします。通常、最初の段落の残りの部分についても同様の形式にするのが適切です。続く段落については、各文を直説法にし、適切な主語を設ける方が一般的に見栄えが良くなります。
• 「はい」か「いいえ」の述語となる関数のドキュメント文字列は、何をもって真とするかを明確に示すため、「Return t if」のような言葉で始めるべきです。「return」という語を用いることで、文の冒頭が小文字の「t」になることを避け、多少の違和感が生じるのを防ぐことができます。
• ドキュメント文字列は、受動態ではなく能動態で、未来形ではなく現在形で記述してください。例えば、「AとBを含むリストが返されます」ではなく、「AとBを含むリストを返します」と記述してください。
• 「cause」（またはそれに相当する表現）を不必要に使用しないでください。「Cause Emacs to display text in boldface」ではなく、単に「Display text in boldface」と記述してください。
• 「iff」（「if and only if」を意味する数学用語）の使用は避けてください。馴染みのない人が多いため、誤字と勘違いされる恐れがあります。ほとんどの場合、「if」だけでも意味は明確です。そうでない場合は、意味が伝わる別の表現を探すようにしてください。
• 「e.g.」（「for example」の略）、「i.e.」（「that is」の略）、「no.」（「number」の略）、「cf.」（「compare」／「see also」の略）、および「w.r.t.」（「with respect to」の略）といった略語は、可能な限り使用しないようにしてください。ほとんどの場合、省略せずに表記した方が分かりやすく、読みやすくなります。³⁹
• コマンドが特定のモードや状況においてのみ意味を持つ場合は、その旨をドキュメント文字列に記載してください。例えば、dired-find-file のドキュメントは以下の通りです：

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

• ユーザーが設定したい可能性のあるオプションを表す変数を定義する場合は、defcustom を使用してください。グローバル変数の定義を参照してください。
• yes-or-noフラグとなる変数のドキュメント文字列は、「Non-nil means」のような言葉で始めるべきです。これにより、nil以外のすべての値が等価であることが明確になり、nilおよびnon-nilが何を意味するのかが明示されます。
• ドキュメント文字列の1行が開き括弧で始まる場合は、次のように開き括弧の前にバックスラッシュを記述することを検討してください。

  The argument FOO can be either a number
  \(a buffer position) or a string (a file name).
  

  これにより、Emacs 27.1より古いバージョンにおいて ‘(’ が defun の開始として扱われていたバグを回避できます（The GNU Emacs Manual の Defuns を参照）。古いバージョンのEmacsでコードを編集する人がいないと想定される場合は、この回避策は不要です。