|
| 1 | +% Rust Documentation |
| 2 | + |
| 3 | +`rustdoc` is the built-in tool for generating documentation. It integrates |
| 4 | +with the compiler to provide accurate hyperlinking between usage of types and |
| 5 | +their documentation. Furthermore, by not using a separate parser, it will |
| 6 | +never reject your valid Rust code. |
| 7 | + |
| 8 | +# Creating Documentation |
| 9 | + |
| 10 | +Documenting Rust APIs is quite simple. To document a given item, we have "doc |
| 11 | +comments": |
| 12 | + |
| 13 | +~~~ |
| 14 | +// the "link" crate attribute is currently required for rustdoc, but normally |
| 15 | +// isn't needed. |
| 16 | +#[link(name="universe")]; |
| 17 | +#[crate_type="lib"]; |
| 18 | +
|
| 19 | +//! Tools for dealing with universes (this is a doc comment, and is shown on |
| 20 | +//! the crate index page. The ! makes it apply to the parent of the comment, |
| 21 | +//! rather than what follows). |
| 22 | +
|
| 23 | +/// Widgets are very common (this is a doc comment, and will show up on |
| 24 | +/// Widget's documentation). |
| 25 | +pub struct Widget { |
| 26 | + /// All widgets have a purpose (this is a doc comment, and will show up |
| 27 | + /// the field's documentation). |
| 28 | + purpose: ~str, |
| 29 | + /// Humans are not allowed to understand some widgets |
| 30 | + understandable: bool |
| 31 | +} |
| 32 | +
|
| 33 | +pub fn recalibrate() { |
| 34 | + //! Recalibrate a pesky universe (this is also a doc comment, like above, |
| 35 | + //! the documentation will be applied to the *parent* item, so |
| 36 | + //! `recalibrate`). |
| 37 | + /* ... */ |
| 38 | +} |
| 39 | +~~~ |
| 40 | + |
| 41 | +Then, one can run `rustdoc universe.rs`. By default, it generates a directory |
| 42 | +called `doc`, with the documentation for `universe` being in |
| 43 | +`doc/universe/index.html`. If you are using other crates with `extern mod`, |
| 44 | +rustdoc will even link to them when you use their types, as long as their |
| 45 | +documentation has already been generated by a previous run of rustdoc, or the |
| 46 | +crate advertises that its documentation is hosted at a given URL. |
| 47 | + |
| 48 | +The generated output can be controlled with the `doc` crate attribute, which |
| 49 | +is how the above advertisement works. An example from the `libstd` |
| 50 | +documentation: |
| 51 | + |
| 52 | +~~~ |
| 53 | +#[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk.png", |
| 54 | + html_favicon_url = "http://www.rust-lang.org/favicon.ico", |
| 55 | + html_root_url = "http://static.rust-lang.org/doc/master")]; |
| 56 | +~~~ |
| 57 | + |
| 58 | +The `html_root_url` is the prefix that rustdoc will apply to any references to |
| 59 | +that crate's types etc. |
| 60 | + |
| 61 | +rustdoc can also generate JSON, for consumption by other tools, with |
| 62 | +`rustdoc --output-format json`, and also consume already-generated JSON with |
| 63 | +`rustdoc --input-format json`. |
| 64 | + |
| 65 | +# Using the Documentation |
| 66 | + |
| 67 | +The web pages generated by rustdoc present the same logical heirarchy that one |
| 68 | +writes a library with. Every kind of item (function, struct, etc) has its own |
| 69 | +color, and one can always click on a colored type to jump to its |
| 70 | +documentation. There is a search bar at the top, which is powered by some |
| 71 | +javascript and a statically-generated search index. No special web server is |
| 72 | +required for the search. |
0 commit comments