Rust: Develop doc-comment style guide

:+1: for discussing this. I want to contribute docs, but I don't want to make more work for you after it's done. ;)

For comparison, standard Python style is to use the imperative "Return the …", which I find works well:

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

Go has settled on the non-imperative style: http://golang.org/pkg/

Visiting for triage.

Personally, I prefer imperative verbs, and a period at the end. As for doc comment style, I don't think we should enforce any particular way over another, at least not while the language defines multiple ways to do it. Also, my preferred way is

/**
 * doc string
 */

I also prefer the imperative. Style also needs to include a unified syntax for refering to types and arguments, so rustdoc can properly annotate/hyperlink them. That's down the road though

Visiting for triage. I have very little opinion about this.

Descriptive style:

• 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
• Haskell: ... 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

Imperative style:

• Ocaml: ... 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

I prefer the descriptive versions myself because a method definition does not do anything until i tell it to:

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

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

I am sensible to kud1ing's argument. Furthermore, if you read aloud a line the way it is presented in the doc:

zero Returns the additive identity, 0.

then the declarative form makes it a real sentence "zero" returns the additive identity, 0..

@Armavica: Which is actually a short form of The method "zero" returns the additive identity, 0.

Documentating and interface is presenting something to the audience. I think the imperative form makes more sense, when you explain what/how/why something is happening in the implementation.

There's also https://github.com/mozilla/rust/issues/9403 about the style of the examples in documentation.

P-low.

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

From the comments here, descriptive style (e.g., "Converts a byte to a string.") seems more popular than imperative style ("Convert a byte to a string."). I don't much care which way we go, but it would be nice to have an official decision on this.

I think that calling this the imperative style is wrong. It's not imperative, because it's not instructing anyone to do anything. I think it's the first-person present indicative. I suspect that the urge to write

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

stems from the mindset of "I am the function. What do I do?", so it's the first-person present indicative.

However, when reading documentation, most readers will naturally treat the function as a third-person singular subject instead of a first-person subject. To that end, the documentation should be written in the third-person singular instead of the first-person.

The only reasonable argument I can see for considering this to be the imperative rather than the first-person present indicative is when the docstring describes a function declaration that the user is expected to implement. This is very common in OO languages, but in Rust that only applies to trait methods. This case suggests the use of the imperative because it's telling you what you must do in order to implement the method correctly.

But I don't consider this argument to be persuasive. The primary use-case for documentation is telling the reader how to _use_ the API, not how to implement it. The number of uses of an API vastly outstrips the number of implementations (in all but the most esoteric of cases). Therefore, I believe that it makes more sense to use the present indicative in the third-person singular than it does to use the imperative, even for trait methods.

Another thing to deal with: hypens or en dashes:

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

The preference for an en dash instead of a hyphen in these coordinate/relationship/connection types of terms is a matter of style preference, not inherent orthographic "correctness"; both are equally "correct", and each is the preferred style in some style guides.

I have submitted an RFC: https://github.com/rust-lang/rfcs/pull/505