Rust: ドキュメントコメントスタイルガイドを作成する

：+1：これを議論するため。 私はドキュメントを寄稿したいのですが、それが終わった後、あなたのためにこれ以上の仕事をしたくありません。 ;）

比較のために、標準のPythonスタイルは、命令型の「Returnthe…」を使用することです。これはうまく機能すると思います。

http://www.python.org/dev/peps/pep-0257/#one -line-docstrings

Goは、命令型ではないスタイルに落ち着きました： http ：

トリアージのための訪問。

個人的には、命令動詞と最後のピリオドが好きです。 ドキュメントのコメントスタイルに関しては、少なくとも言語がそれを行うための複数の方法を定義している間は、特定の方法を別の方法に強制するべきではないと思います。 また、私の好みの方法は

/**
 * doc string
 */

私も命令を好みます。 スタイルには、型と引数を参照するための統一された構文も含める必要があるため、 rustdocはそれらに適切に注釈を付けたりハイパーリンクしたりできます。 しかし、それは道のりです

トリアージのための訪問。 私はこれについてほとんど意見がありません。

記述的なスタイル：

• C＃ ： Sorts the elements ... http://msdn.microsoft.com/en-gb/library/w56d4y5z%28v=vs.85%29.aspx#United％20Kingdom％20％28English％29
• C ++ ： ... sorts the elements ... http://www.sgi.com/tech/stl/sort.html
• Go ： ... sorts data ... http://golang.org/pkg/sort/#Sort
• Haskel l： ... takes an element and a list and inserts the element into the list ... http://hackage.haskell.org/package/base-4.6.0.1/docs/Data-List.html
• Java ： Sorts the specified array ... http://docs.oracle.com/javase/7/docs/api/java/util/Arrays.html
• Ruby ： Sorts self in place. http://www.ruby-doc.org/core-2.1.0/Array.html#method -i-sort-21

命令型：

• Ocam l： ... sort a list ... http://caml.inria.fr/pub/docs/manual-ocaml/libref/List.html
• Python ： Sort the items ... http://docs.python.org/2/tutorial/datastructures.html

メソッド定義は次のように指示するまで何もしないので、私は記述バージョンを自分で好みます。

class Machine
{
    // Self-destructs the machine, if necessary.
    void self_destruct();
};

// Self-destruct!
if ( emergency )
  machine.self_destruct();

私はkud1ingの議論に敏感です。 さらに、ドキュメントに示されている方法で行を読み上げると、次のようになります。

ゼロ加法単位元0を返します。

次に、宣言型はそれを実際の文"zero" returns the additive identity, 0.ます。

@Armavica ：これは実際にはThe method "zero" returns the additive identity, 0短縮形です。

文書化とインターフェースは、聴衆に何かを提示しています。 実装で何が/どのように/なぜ起こっているのかを説明するときは、命令形の方が理にかなっていると思います。

ドキュメントの例のスタイルについては、 https：//github.com/mozilla/rust/issues/9403もあります。

P-low。

cc https://github.com/mozilla/rust/issues/12928

ここでのコメントから、記述型（「バイトを文字列に変換する」など）は命令型（「バイトを文字列に変換する」）よりも人気があるようです。 どちらに行くかはあまり気にしませんが、正式に決定しておくといいでしょう。

これを命令型と呼ぶのは間違っていると思います。 誰かに何かをするように指示していないので、それは必須ではありません。 一人称プレゼントだと思います。 書きたいという衝動があるのではないかと思います

/// Frob the twaddle.
fn frob() {}

「私は機能です。私は何をしますか？」という考え方に由来するので、それは一人称の現在形を示しています。

ただし、ドキュメントを読むとき、ほとんどの読者は当然、機能を一人称の主題ではなく、三人称の単数の主題として扱います。 そのためには、ドキュメントは一人称ではなく三人称単数で書く必要があります。

これを一人称現在形ではなく命令型と見なすために私が見ることができる唯一の合理的な議論は、docstringがユーザーが実装することが期待される関数宣言を記述している場合です。 これはオブジェクト指向言語では非常に一般的ですが、Rustではトレイトメソッドにのみ適用されます。 このケースは、メソッドを正しく実装するために何をしなければならないかを示しているため、命令の使用を示唆しています。

しかし、私はこの議論が説得力があるとは考えていません。 ドキュメントの主な使用例は、APIの実装方法ではなく、APIの使用方法を読者に伝えることです。 APIの使用数は、実装の数を大幅に上回っています（最も難解な場合を除くすべての場合）。 したがって、特性法であっても、命令法を使用するよりも、第三者単数で現在形を使用する方が理にかなっていると思います。

対処すべきもう1つのこと：ハイフンまたはダッシュ：

https://en.wikipedia.org/wiki/Dash#Relationships_and_connections

これらの座標/関係/接続タイプの用語でハイフンの代わりにダッシュを優先することは、スタイルの優先事項の問題であり、固有の正書法の「正確さ」ではありません。 どちらも同じように「正しい」ものであり、一部のスタイルガイドではそれぞれが推奨されるスタイルです。

RFCを提出しました： https ：