% Rust Documentation

`rustdoc` is the built-in tool for generating documentation. It integrates
with the compiler to provide accurate hyperlinking between usage of types and
their documentation. Furthermore, by not using a separate parser, it will
never reject your valid Rust code.

# Creating Documentation

Documenting Rust APIs is quite simple. To document a given item, we have "doc
comments":

~~~
// the "link" crate attribute is currently required for rustdoc, but normally
// isn't needed.
#[pkgid = "universe"];
#[crate_type="lib"];

//! Tools for dealing with universes (this is a doc comment, and is shown on
//! the crate index page. The ! makes it apply to the parent of the comment,
//! rather than what follows).

/// Widgets are very common (this is a doc comment, and will show up on
/// Widget's documentation).
pub struct Widget {
	/// All widgets have a purpose (this is a doc comment, and will show up
	/// the field's documentation).
	purpose: ~str,
	/// Humans are not allowed to understand some widgets
	understandable: bool
}

pub fn recalibrate() {
	//! Recalibrate a pesky universe (this is also a doc comment, like above,
	//! the documentation will be applied to the *parent* item, so
	//! `recalibrate`).
	/* ... */
}
~~~

Doc comments are markdown, and are currently parsed with the
[sundown][sundown] library. rustdoc does not yet do any fanciness such as
referencing other items inline, like javadoc's `@see`. One exception to this
is that the first paragrah will be used as the "summary" of an item in the
generated documentation:

~~~
/// A whizbang. Does stuff. (this line is the summary)
///
/// Whizbangs are ...
struct Whizbang;
~~~

To generate the docs, run `rustdoc universe.rs`. By default, it generates a
directory called `doc`, with the documentation for `universe` being in
`doc/universe/index.html`. If you are using other crates with `extern mod`,
rustdoc will even link to them when you use their types, as long as their
documentation has already been generated by a previous run of rustdoc, or the
crate advertises that its documentation is hosted at a given URL.

The generated output can be controlled with the `doc` crate attribute, which
is how the above advertisement works. An example from the `libstd`
documentation:

~~~
#[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
      html_favicon_url = "http://www.rust-lang.org/favicon.ico",
      html_root_url = "http://static.rust-lang.org/doc/master")];
~~~

The `html_root_url` is the prefix that rustdoc will apply to any references to
that crate's types etc.

rustdoc can also generate JSON, for consumption by other tools, with
`rustdoc --output-format json`, and also consume already-generated JSON with
`rustdoc --input-format json`.

# Using the Documentation

The web pages generated by rustdoc present the same logical heirarchy that one
writes a library with. Every kind of item (function, struct, etc) has its own
color, and one can always click on a colored type to jump to its
documentation. There is a search bar at the top, which is powered by some
javascript and a statically-generated search index. No special web server is
required for the search.

[sundown]: https://github.com/vmg/sundown/