```
This code generates documentation that looks [like this][rc-new]. I've left the
-implementation out, with a regular comment in its place. That's the first thing
-to notice about this annotation: it uses `///`, instead of `//`. The triple slash
+implementation out, with a regular comment in its place.
+
+The first thing to notice about this annotation is that it uses
+`///` instead of `//`. The triple slash
indicates a documentation comment.
Documentation comments are written in Markdown.
Rust keeps track of these comments, and uses them when generating
documentation. This is important when documenting things like enums:
-```
+```rust
/// The `Option` type. See [the module level documentation](../) for more.
enum Option<T> {
/// No value
Anyway, let's cover each part of this comment in detail:
-```
+```rust
/// Constructs a new `Rc<T>`.
# fn foo() {}
```
The first line of a documentation comment should be a short summary of its
functionality. One sentence. Just the basics. High level.
-```
+```rust
///
/// Other details about constructing `Rc<T>`s, maybe describing complicated
/// semantics, maybe additional options, all kinds of stuff.
#### Special sections
-```
+```rust
/// # Examples
# fn foo() {}
```
are three kinds of headers that are commonly used. They aren't special syntax,
just convention, for now.
-```
+```rust
/// # Panics
# fn foo() {}
```
least. If your function has a non-trivial contract like this, that is
detected/enforced by panics, documenting it is very important.
-```
+```rust
/// # Failures
# fn foo() {}
```
slightly less important than `Panics`, because failure is encoded into the type
system, but it's still a good thing to do.
-```
+```rust
/// # Safety
# fn foo() {}
```
If your function is `unsafe`, you should explain which invariants the caller is
responsible for upholding.
-```
+```rust
/// # Examples
///
/// ```
code block annotations, which we'll talk about in a moment, and can have
more than one section:
-```
+```rust
/// # Examples
///
/// Simple `&str` patterns:
To write some Rust code in a comment, use the triple graves:
-```
+```rust
/// ```
/// println!("Hello, world");
/// ```
If you want something that's not Rust code, you can add an annotation:
-```
+```rust
/// ```c
/// printf("Hello, world\n");
/// ```
Let's discuss our sample example documentation:
-```
+```rust
/// ```
/// println!("Hello, world");
/// ```
automatically add a main() wrapper around your code, and in the right place.
For example:
-```
+```rust
/// ```
/// use std::rc::Rc;
///
This will end up testing:
-```
+```rust
fn main() {
use std::rc::Rc;
let five = Rc::new(5);
looks different than the output:
-```
+```rust
/// Some documentation.
# fn foo() {}
```
longer examples in detail, while still preserving the testability of your
documentation. For example, this code:
-```
+```rust
let x = 5;
let y = 6;
println!("{}", x + y);
First, we set `x` to five:
-```
+```rust
let x = 5;
# let y = 6;
# println!("{}", x + y);
Next, we set `y` to six:
-```
+```rust
# let x = 5;
let y = 6;
# println!("{}", x + y);
Finally, we print the sum of `x` and `y`:
-```
+```rust
# let x = 5;
# let y = 6;
println!("{}", x + y);
Here’s an example of documenting a macro:
-```
+```rust
/// Panic with a given message unless an expression evaluates to true.
///
/// # Examples
$ cargo test
```
-That's right, `cargo test` tests embedded documentation too. However,
+That's right, `cargo test` tests embedded documentation too. However,
`cargo test` will not test binary crates, only library ones. This is
due to the way `rustdoc` works: it links against the library to be tested,
but with a binary, there’s nothing to link to.
There are a few more annotations that are useful to help `rustdoc` do the right
thing when testing your code:
-```
+```rust
/// ```ignore
/// fn foo() {
/// ```
with `text` if it's not code, or using `#`s to get a working example that
only shows the part you care about.
-```
+```rust
/// ```should_panic
/// assert!(false);
/// ```
`should_panic` tells `rustdoc` that the code should compile correctly, but
not actually pass as a test.
-```
+```rust
/// ```no_run
/// loop {
/// println!("Hello, world");
Rust has another kind of doc comment, `//!`. This comment doesn't document the next item, but the enclosing item. In other words:
-```
+```rust
mod foo {
//! This is documentation for the `foo` module.
//!
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:
-```
+```rust
//! A module for using `foo`s.
//!
//! The `foo` module contains a lot of useful functionality blah blah blah
When you write documentation in Markdown files, you don't need to prefix
the documentation with comments. For example:
-```
+```rust
/// # Examples
///
/// ```
At a deeper level, documentation comments are sugar for documentation attributes:
-```
+```rust
/// this
# fn foo() {}
are the same, as are these:
-```
+```rust
//! this
#![doc="/// this"]
You can control a few aspects of the HTML that `rustdoc` generates through the
`#![doc]` version of the attribute:
-```
+```rust
#![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/")];
+ html_root_url = "http://doc.rust-lang.org/")]
```
This sets a few different options, with a logo, favicon, and a root URL.
projects / rust.git / blobdiff