Rust: 开发文档评论风格指南

创建于 2013-01-05 · 17评论 · 资料来源: rust-lang/rust

在 1.0 版本之前，很多库代码预计会发生变化，现在这样做没有多大意义，但核心和标准库应该使用一致的 API 文档样式。 wiki尝试指定约定，但这些需要充实并实际应用于代码库。

现在，一些文档评论是用第三人称指示写的：

pub fn map<T, U>(opt: &Option<T>, f: fn(x: &T) -> U) -> Option<U> {
    //! Maps a `some` value by reference from one type to another

有些是用命令式写的：

pub fn chain<T, U>(opt: Option<T>,
                   f: fn(t: T) -> Option<U>) -> Option<U> {
    /*!
     * Update an optional value by optionally running its content through a
     * function that returns an option.
     */

这两个例子说明了另一个不一致之处：一些摘要（评论的第一行）没有结束标点符号，而另一些则以句点结尾。

另一件不同的事情是评论风格本身。一些文档评论看起来像

/*!
 * foo...
 * bar...
 * baz...
 */

而其他人看起来像

/*!
 foo...
 bar...
 baz...
 */

一旦这些规则（和其他规则）被编纂，我很乐意开始浏览文档注释并更新它们。

P-low

资料来源

ghost

最有用的评论

描述风格：

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
去： ... 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
红宝石： 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

kud1ing 于 2014-01-28

👍2

所有17条评论

:+1: 讨论这个。我想贡献文档，但我不想在完成后为你做更多的工作。 ;)

steveklabnik 于 2013-01-05

为了进行比较，标准的 Python 风格是使用命令式“返回 ...”，我发现它很有效：

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

sophiebits 于 2013-01-06

Go 已经确定了非命令式风格： http :

kud1ing 于 2013-01-06

探视分流。

就个人而言，我更喜欢命令式动词，并在结尾处加一个句号。至于文档注释风格，我认为我们不应该强制执行任何特定的方式，至少在语言定义了多种方式来做到这一点时。另外，我的首选方式是

/**
 * doc string
 */

bblum 于 2013-07-03

我也更喜欢命令式。样式还需要包含用于引用类型和参数的统一语法，因此rustdoc可以正确地注释/超链接它们。虽然那是在路上

emberian 于 2013-07-07

探视分流。对此，我的意见很少。

msullivan 于 2013-08-23

描述风格：

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
去： ... 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
红宝石： 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

kud1ing 于 2014-01-28

👍2

我自己更喜欢描述性版本，因为方法定义在我告诉它之前不会做任何事情：

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

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

kud1ing 于 2014-01-28

我对 kud1ing 的论点是明智的。此外，如果您按照文档中显示的方式大声朗读一行：