Develop doc-comment style guide

[ghost]

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.

[brson]

cc #12928

[lkuper]

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.

[lilyball]

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.

[steveklabnik]

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.

[steveklabnik]

I have submitted an RFC: rust-lang/rfcs#505