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.
8 # Creating Documentation
10 Documenting Rust APIs is quite simple. To document a given item, we have "doc
14 # #![allow(unused_attribute)]
15 // the "link" crate attribute is currently required for rustdoc, but normally
17 #![crate_id = "universe"]
20 //! Tools for dealing with universes (this is a doc comment, and is shown on
21 //! the crate index page. The ! makes it apply to the parent of the comment,
22 //! rather than what follows).
24 # mod workaround_the_outer_function_rustdoc_inserts {
25 /// Widgets are very common (this is a doc comment, and will show up on
26 /// Widget's documentation).
28 /// All widgets have a purpose (this is a doc comment, and will show up
29 /// the field's documentation).
31 /// Humans are not allowed to understand some widgets
35 pub fn recalibrate() {
36 //! Recalibrate a pesky universe (this is also a doc comment, like above,
37 //! the documentation will be applied to the *parent* item, so
44 Documentation can also be controlled via the `doc` attribute on items. This is
45 implicitly done by the compiler when using the above form of doc comments
46 (converting the slash-based comments to `#[doc]` attributes).
50 Calculates the factorial of a number.
52 Given the input integer `n`, this function will calculate `n!` and return it.
54 pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n - 1)} }
58 The `doc` attribute can also be used to control how rustdoc emits documentation
62 // Rustdoc will inline documentation of a `pub use` into this crate when the
63 // `pub use` reaches across crates, but this behavior can also be disabled.
65 pub use std::option::Option;
69 Doc comments are markdown, and are currently parsed with the
70 [hoedown][hoedown] library. rustdoc does not yet do any fanciness such as
71 referencing other items inline, like javadoc's `@see`. One exception to this
72 is that the first paragraph will be used as the "summary" of an item in the
73 generated documentation:
76 /// A whizbang. Does stuff. (this line is the summary)
82 To generate the docs, run `rustdoc universe.rs`. By default, it generates a
83 directory called `doc`, with the documentation for `universe` being in
84 `doc/universe/index.html`. If you are using other crates with `extern crate`,
85 rustdoc will even link to them when you use their types, as long as their
86 documentation has already been generated by a previous run of rustdoc, or the
87 crate advertises that its documentation is hosted at a given URL.
89 The generated output can be controlled with the `doc` crate attribute, which
90 is how the above advertisement works. An example from the `libstd`
94 #[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
95 html_favicon_url = "http://www.rust-lang.org/favicon.ico",
96 html_root_url = "http://doc.rust-lang.org/")];
99 The `html_root_url` is the prefix that rustdoc will apply to any references to
100 that crate's types etc.
102 rustdoc can also generate JSON, for consumption by other tools, with
103 `rustdoc --output-format json`, and also consume already-generated JSON with
104 `rustdoc --input-format json`.
106 rustdoc also supports personalizing the output from crates' documentation,
107 similar to markdown options.
109 - `--html-in-header FILE`: includes the contents of `FILE` at the
110 end of the `<head>...</head>` section.
111 - `--html-before-content FILE`: includes the contents of `FILE`
112 directly after `<body>`, before the rendered content (including the
114 - `--html-after-content FILE`: includes the contents of `FILE`
115 after all the rendered content.
117 # Using the Documentation
119 The web pages generated by rustdoc present the same logical hierarchy that one
120 writes a library with. Every kind of item (function, struct, etc) has its own
121 color, and one can always click on a colored type to jump to its
122 documentation. There is a search bar at the top, which is powered by some
123 JavaScript and a statically-generated search index. No special web server is
124 required for the search.
126 [hoedown]: https://github.com/hoedown/hoedown
128 # Testing the Documentation
130 `rustdoc` has support for testing code examples which appear in the
131 documentation. This is helpful for keeping code examples up to date with the
134 To test documentation, the `--test` argument is passed to rustdoc:
137 rustdoc --test crate.rs
142 Rust documentation currently uses the markdown format, and rustdoc treats all
143 code blocks as testable-by-default unless they carry a language tag of another
144 language. In order to not run a test over a block of code, the `ignore` string
145 can be added to the three-backtick form of markdown code block.
149 // This is a testable code block
153 // This is rust and also testable
157 // This is not a testable code block
160 // This is a testable code block (4-space indent)
163 # this is shell code and not tested
167 You can specify that the test's execution should fail with the `should_fail`
172 // This code block is expected to generate a panic when run
176 You can specify that the code block should be compiled but not run with the
181 // This code will be compiled but not executed
185 Lastly, you can specify that a code block be compiled as if `--test`
186 were passed to the compiler using the `test_harness` directive.
192 panic!("oops! (will run & register as a failed test)")
197 Rustdoc also supplies some extra sugar for helping with some tedious
198 documentation examples. If a line is prefixed with `# `, then the line
199 will not show up in the HTML documentation, but it will be used when
200 testing the code block (NB. the space after the `#` is required, so
201 that one can still write things like `#[derive(Eq)]`).
205 # /!\ The three following lines are comments, which are usually stripped off by
206 # the doc-generating tool. In order to display them anyway in this particular
207 # case, the character following the leading '#' is not a usual space like in
208 # these first five lines but a non breakable one.
209 # // showing 'fib' in this documentation would just be tedious and detracts from
210 # // what's actually being documented.
211 # fn fib(n: int) { n + 2 }
213 spawn(move || { fib(200); })
217 The documentation online would look like `spawn(move || { fib(200); })`, but when
218 testing this code, the `fib` function will be included (so it can compile).
220 Rustdoc will automatically add a `main()` wrapper around your code, and in the right
227 /// let five = Rc::new(5);
232 This will end up testing:
237 let five = Rc::new(5);
241 Here's the full algorithm:
243 1. Given a code block, if it does not contain `fn main`, it is wrapped in `fn main() { your_code }`
244 2. Given that result, if it contains no `extern crate` directives but it also
245 contains the name of the crate being tested, then `extern crate <name>` is
247 3. Some common `allow` attributes are added for documentation examples at the top.
249 ## Running tests (advanced)
251 Running tests often requires some special configuration to filter tests, find
252 libraries, or try running ignored examples. The testing framework that rustdoc
253 uses is built on crate `test`, which is also used when you compile crates with
254 rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness
255 with the `--test-args` flag.
258 # Only run tests containing 'foo' in their name
259 $ rustdoc --test lib.rs --test-args 'foo'
261 # See what's possible when running tests
262 $ rustdoc --test lib.rs --test-args '--help'
265 When testing a library, code examples will often show how functions are used,
266 and this code often requires `use`-ing paths from the crate. To accommodate this,
267 rustdoc will implicitly add `extern crate <crate>;` where `<crate>` is the name of
268 the crate being tested to the top of each code example. This means that rustdoc
269 must be able to find a compiled version of the library crate being tested. Extra
270 search paths may be added via the `-L` flag to `rustdoc`.
272 # Standalone Markdown files
274 As well as Rust crates, rustdoc supports rendering pure Markdown files
275 into HTML and testing the code snippets from them. A Markdown file is
276 detected by a `.md` or `.markdown` extension.
278 There are 4 options to modify the output that Rustdoc creates.
280 - `--markdown-css PATH`: adds a `<link rel="stylesheet">` tag pointing to `PATH`.
281 - `--html-in-header FILE`: includes the contents of `FILE` at the
282 end of the `<head>...</head>` section.
283 - `--html-before-content FILE`: includes the contents of `FILE`
284 directly after `<body>`, before the rendered content (including the
286 - `--html-after-content FILE`: includes the contents of `FILE`
287 directly before `</body>`, after all the rendered content.
289 All of these can be specified multiple times, and they are output in
290 the order in which they are specified. The first line of the file being rendered must
291 be the title, prefixed with `%` (e.g. this page has `% Rust
292 Documentation` on the first line).
294 Like with a Rust crate, the `--test` argument will run the code
295 examples to check they compile, and obeys any `--test-args` flags. The
296 tests are named after the last `#` heading.