Change:
Here's the full algorithm: <del> 1. Given a code block, if it does not contain `fn main`, it is wrapped in `fn main() { your_code }` </del> <ins> 1. Given a code block, if it does not contain `fn main()`, it is wrapped in `fn main() { your_code }` </ins> 2. Given that result, if it contains no `extern crate` directives but it also contains the name of the crate being tested, then `extern crate <name>` is injected at the top. <del> 3. Some common `allow` attributes are added for documentation examples at the top. </del> <ins> 3. Some common allow attributes are added for documentation examples at the top. Sometimes, this isn't enough, though. For example, all of these code samples with `///` we've been talking about? The raw text: ```text /// Some documentation. # fn foo() {} ``` looks different than the output: ``` /// Some documentation. # fn foo() {} ``` Yes, that's right: you can add lines that start with `# `, and they will be hidden from the output, but will be used when compiling your code. You can use this to your advantage. In this case, documentation comments need to apply to some kind of function, so if I want to show you just a documentation comment, I need to add a little function definition below it. At the same time, it's just there to satisfy the compiler, so hiding it makes the example more clear. You can use this technique to explain longer examples in detail, while still preserving the testability of your documentation. For example, this code: ``` let x = 5; let y = 6; println!("{}", x + y); ``` Here's an explanation, rendered: First, we set `x` to five: ``` let x = 5; # let y = 6; # println!("{}", x + y); ``` Next, we set `y` to six: ``` # let x = 5; let y = 6; # println!("{}", x + y); ``` Finally, we print the sum of `x` and `y`: ``` # let x = 5; # let y = 6; println!("{}", x + y); ``` Here's the same explanation, in raw text: > First, we set `x` to five: > > ```text > let x = 5; > # let y = 6; > # println!("{}", x + y); > ``` > > Next, we set `y` to six: > > ```text > # let x = 5; > let y = 6; > # println!("{}", x + y); > ``` > > Finally, we print the sum of `x` and `y`: > > ```text > # let x = 5; > # let y = 6; > println!("{}", x + y); > ``` By repeating all parts of the example, you can ensure that your example still compiles, while only showing the parts that are relevant to that part of your explanation. To run the tests, either ```bash $ rustdoc --test path/to/my/crate/root.rs # or $ cargo test ``` That's right, `cargo test` tests embedded documentation too. There are a few more annotations that are useful to help `rustdoc` do the right thing when testing your code: ``` /// ```ignore /// fn foo() { /// ``` # fn foo() {} ``` The `ignore` directive tells Rust to ignore your code. This is almost never what you want, as it's the most generic. Instead, consider annotating it with `text` if it's not code, or using `#`s to get a working example that only shows the part you care about. ``` /// ```should_panic /// assert!(false); /// ``` # fn foo() {} ``` `should_panic` tells `rustdoc` that the code should compile correctly, but not actually pass as a test. ``` /// ```no_run /// loop { ///     println!("Hello, world"); /// } /// ``` # fn foo() {} ``` The `no_run` attribute will compile your code, but not run it. This is important for examples such as "Here's how to start up a network service," which you would want to make sure compile, but might run in an infinite loop! ### Documenting modules Rust has another kind of doc comment, `//!`. This comment doesn't document the next item, but the enclosing item. In other words: ``` mod foo { //! This is documentation for the `foo` module. //! //! # Examples // ... } ``` This is where you'll see `//!` used most often: for module documentation. If you have a module in `foo.rs`, you'll often open its code and see this: ``` //! A module for using `foo`s. //! //! The `foo` module contains a lot of useful functionality blah blah blah ``` ### Documentation comment style Check out [RFC 505][rfc505] for full conventions around the style and format of documentation. [rfc505]: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md ## Other documentation All of this behavior works in non-Rust source files too. Because comments are written in Markdown, they're often `.md` files. When you write documentation in Markdown files, you don't need to prefix the documentation with comments. For example: </ins> <del> ## Running tests (advanced) </del> <ins> ``` /// # Examples /// /// ``` /// use std::rc::Rc; /// /// let five = Rc::new(5); /// ``` # fn foo() {} ``` </ins> <del> Running tests often requires some special configuration to filter tests, find libraries, or try running ignored examples. The testing framework that rustdoc uses is built on crate `test`, which is also used when you compile crates with rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness with the `--test-args` flag. </del> <ins> is just </ins> <del> ~~~console # Only run tests containing 'foo' in their name $ rustdoc --test lib.rs --test-args 'foo' </del> <ins> ~~~markdown # Examples </ins> <del> # See what's possible when running tests $ rustdoc --test lib.rs --test-args '--help' </del> <ins> ``` use std::rc::Rc; let five = Rc::new(5); ``` </ins> ~~~ <del> When testing a library, code examples will often show how functions are used, and this code often requires `use`-ing paths from the crate. To accommodate this, rustdoc will implicitly add `extern crate <crate>;` where `<crate>` is the name of the crate being tested to the top of each code example. This means that rustdoc must be able to find a compiled version of the library crate being tested. Extra search paths may be added via the `-L` flag to `rustdoc`. </del> <ins> when it's in a Markdown file. There is one wrinkle though: Markdown files need to have a title like this: </ins> <del> # Standalone Markdown files </del> <ins> ```markdown % The title </ins> <del> As well as Rust crates, rustdoc supports rendering pure Markdown files into HTML and testing the code snippets from them. A Markdown file is detected by a `.md` or `.markdown` extension. </del> <ins> This is the example documentation. ``` This `%` line needs to be the very first line of the file. ## `doc` attributes At a deeper level, documentation comments are sugar for documentation attributes: ``` /// this # fn foo() {} #[doc="this"] # fn bar() {} ``` </ins> <del> There are 4 options to modify the output that Rustdoc creates. </del> <ins> are the same, as are these: </ins> <del> - `--markdown-css PATH`: adds a `<link rel="stylesheet">` tag pointing to `PATH`. - `--html-in-header FILE`: includes the contents of `FILE` at the end of the `<head>...</head>` section. - `--html-before-content FILE`: includes the contents of `FILE` directly after `<body>`, before the rendered content (including the title). - `--html-after-content FILE`: includes the contents of `FILE` directly before `</body>`, after all the rendered content. </del> <ins> ``` //! this </ins> <del> All of these can be specified multiple times, and they are output in the order in which they are specified. The first line of the file being rendered must be the title, prefixed with `%` (e.g. this page has `% Rust Documentation` on the first line). </del> <ins> #![doc="/// this"] ``` </ins> <del> Like with a Rust crate, the `--test` argument will run the code examples to check they compile, and obeys any `--test-args` flags. The tests are named after the last `#` heading. </del> <ins> You won't often see this attribute used for writing documentation, but it can be useful when changing some options, or when writing a macro. </ins> <del> # Re-exports </del> <ins> ### Re-exports </ins> <del> Rustdoc will show the documentation for a publc re-export in both places: </del> <ins> `rustdoc` will show the documentation for a publc re-export in both places: </ins> <del> ```{rust,ignore} </del> <ins> ```ignore </ins> extern crate foo; pub use foo::bar; ``` <del> This will create documentation for `bar` both inside the documentation for the crate `foo`, as well as the documentation for your crate. It will use the same documentation in both places. </del> <ins> This will create documentation for bar both inside the documentation for the crate `foo`, as well as the documentation for your crate. It will use the same documentation in both places. </ins> This behavior can be supressed with `no_inline`: <del> ```{rust,ignore} </del> <ins> ```ignore </ins> extern crate foo; #[doc(no_inline)] pub use foo::bar; ``` <ins> ### Controlling HTML You can control a few aspects of the HTML that `rustdoc` generates through the `#![doc]` version of the attribute: ``` #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", html_favicon_url = "http://www.rust-lang.org/favicon.ico", html_root_url = "http://doc.rust-lang.org/")]; ``` This sets a few different options, with a logo, favicon, and a root URL. ## Generation options `rustdoc` also contains a few other options on the command line, for further customiziation: - `--html-in-header FILE`: includes the contents of FILE at the end of the `<head>...</head>` section. - `--html-before-content FILE`: includes the contents of FILE directly after `<body>`, before the rendered content (including the search bar). - `--html-after-content FILE`: includes the contents of FILE after all the rendered content. </ins>

Discussion:
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 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: and some are written in the imperative: 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 while others look like Once these rules (and others) are codified, I'd be happy to start going through the doc-comments and updating them.
:+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:
Go has settled on the non-imperative style:
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
I also prefer the imperative. Style also needs to include a unified syntax for refering to types and arguments, so can properly annotate/hyperlink them. That's down the road though
Visiting for triage. I have very little opinion about this.
Descriptive style: C#: C++: Go: Haskell: Java: Ruby: Imperative style: Ocaml: Python:
I prefer the descriptive versions myself because a method definition does not do anything until i tell it to:
I am sensible to kud1ing's argument. Furthermore, if you read aloud a line the way it is presented in the doc: then the declarative form makes it a real sentence .
Which is actually a short form of . 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 about the style of the examples in documentation.
P-low.

cc
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 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:
I have submitted an RFC: