Develop doc-comment style guide

With a lot of library code expected to change before the 1.0 release, it doesn't make much sense to do this now, but the core and std libraries should use a consistent style for API documentation. The wiki makes some attempt at specifying conventions, but these need to be fleshed out and actually applied to the codebase.

Right now, some doc-comments are written in the third-person indicative:

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

and some are written in the imperative:

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.
     */

These two examples illustrate another inconsistency: Some summaries (the first line of the comment) have no terminal punctuation, while others end with a period.

One more thing that varies is the comment style itself. Some doc-comments look like

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

while others look like

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

Once these rules (and others) are codified, I'd be happy to start going through the doc-comments and updating them.

[steveklabnik]

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

[sophiebits]

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

[kud1ing]

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

[bblum]

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
 */

[emberian]

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

[msullivan]

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

[kud1ing]

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

[kud1ing]

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();

[Armavica]

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

[kud1ing]

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

[huonw]

There's also #9403 about the style of the examples in documentation.

[pnkfelix]

P-low.