|
1 | 1 | % Rust Documentation |
2 | 2 |
|
3 | | -This has been moved [into the book](book/documentation.html). |
| 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 | +# #![allow(unused_attribute)] |
| 15 | +// the "link" crate attribute is currently required for rustdoc, but normally |
| 16 | +// isn't needed. |
| 17 | +#![crate_id = "universe"] |
| 18 | +#![crate_type="lib"] |
| 19 | +
|
| 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). |
| 23 | +
|
| 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). |
| 27 | +pub struct Widget { |
| 28 | + /// All widgets have a purpose (this is a doc comment, and will show up |
| 29 | + /// the field's documentation). |
| 30 | + purpose: String, |
| 31 | + /// Humans are not allowed to understand some widgets |
| 32 | + understandable: bool |
| 33 | +} |
| 34 | +
|
| 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 |
| 38 | + //! `recalibrate`). |
| 39 | + /* ... */ |
| 40 | +} |
| 41 | +# } |
| 42 | +~~~ |
| 43 | + |
| 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). |
| 47 | + |
| 48 | +~~~ |
| 49 | +#[doc = " |
| 50 | +Calculates the factorial of a number. |
| 51 | +
|
| 52 | +Given the input integer `n`, this function will calculate `n!` and return it. |
| 53 | +"] |
| 54 | +pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n - 1)} } |
| 55 | +# fn main() {} |
| 56 | +~~~ |
| 57 | + |
| 58 | +The `doc` attribute can also be used to control how rustdoc emits documentation |
| 59 | +in some cases. |
| 60 | + |
| 61 | +``` |
| 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. |
| 64 | +#[doc(no_inline)] |
| 65 | +pub use std::option::Option; |
| 66 | +# fn main() {} |
| 67 | +``` |
| 68 | + |
| 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: |
| 74 | + |
| 75 | +~~~ |
| 76 | +/// A whizbang. Does stuff. (this line is the summary) |
| 77 | +/// |
| 78 | +/// Whizbangs are ... |
| 79 | +struct Whizbang; |
| 80 | +~~~ |
| 81 | + |
| 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. |
| 88 | + |
| 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` |
| 91 | +documentation: |
| 92 | + |
| 93 | +~~~ |
| 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/")]; |
| 97 | +~~~ |
| 98 | + |
| 99 | +The `html_root_url` is the prefix that rustdoc will apply to any references to |
| 100 | +that crate's types etc. |
| 101 | + |
| 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`. |
| 105 | + |
| 106 | +rustdoc also supports personalizing the output from crates' documentation, |
| 107 | +similar to markdown options. |
| 108 | + |
| 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 |
| 113 | + search bar). |
| 114 | +- `--html-after-content FILE`: includes the contents of `FILE` |
| 115 | + after all the rendered content. |
| 116 | + |
| 117 | +# Using the Documentation |
| 118 | + |
| 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. |
| 125 | + |
| 126 | +[hoedown]: https://github.com/hoedown/hoedown |
| 127 | + |
| 128 | +# Testing the Documentation |
| 129 | + |
| 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 |
| 132 | +source code. |
| 133 | + |
| 134 | +To test documentation, the `--test` argument is passed to rustdoc: |
| 135 | + |
| 136 | +~~~ {.sh} |
| 137 | +rustdoc --test crate.rs |
| 138 | +~~~ |
| 139 | + |
| 140 | +## Defining tests |
| 141 | + |
| 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. |
| 146 | + |
| 147 | +~~~md |
| 148 | +``` |
| 149 | +// This is a testable code block |
| 150 | +``` |
| 151 | + |
| 152 | +```rust{.example} |
| 153 | +// This is rust and also testable |
| 154 | +``` |
| 155 | + |
| 156 | +```ignore |
| 157 | +// This is not a testable code block |
| 158 | +``` |
| 159 | + |
| 160 | + // This is a testable code block (4-space indent) |
| 161 | + |
| 162 | +```sh |
| 163 | +# this is shell code and not tested |
| 164 | +``` |
| 165 | +~~~ |
| 166 | + |
| 167 | +You can specify that the test's execution should fail with the `should_fail` |
| 168 | +directive. |
| 169 | + |
| 170 | +~~~md |
| 171 | +```should_fail |
| 172 | +// This code block is expected to generate a panic when run |
| 173 | +``` |
| 174 | +~~~ |
| 175 | + |
| 176 | +You can specify that the code block should be compiled but not run with the |
| 177 | +`no_run` directive. |
| 178 | + |
| 179 | +~~~md |
| 180 | +```no_run |
| 181 | +// This code will be compiled but not executed |
| 182 | +``` |
| 183 | +~~~ |
| 184 | + |
| 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. |
| 187 | + |
| 188 | +~~~md |
| 189 | +```test_harness |
| 190 | +#[test] |
| 191 | +fn foo() { |
| 192 | + panic!("oops! (will run & register as a failed test)") |
| 193 | +} |
| 194 | +``` |
| 195 | +~~~ |
| 196 | + |
| 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)]`). |
| 202 | + |
| 203 | +~~~md |
| 204 | +``` |
| 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 } |
| 212 | + |
| 213 | +spawn(move || { fib(200); }) |
| 214 | +``` |
| 215 | +~~~ |
| 216 | + |
| 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). |
| 219 | + |
| 220 | +Rustdoc will automatically add a `main()` wrapper around your code, and in the right |
| 221 | +place. For example: |
| 222 | + |
| 223 | +``` |
| 224 | +/// ``` |
| 225 | +/// use std::rc::Rc; |
| 226 | +/// |
| 227 | +/// let five = Rc::new(5); |
| 228 | +/// ``` |
| 229 | +# fn foo() {} |
| 230 | +``` |
| 231 | + |
| 232 | +This will end up testing: |
| 233 | + |
| 234 | +``` |
| 235 | +fn main() { |
| 236 | + use std::rc::Rc; |
| 237 | + let five = Rc::new(5); |
| 238 | +} |
| 239 | +``` |
| 240 | + |
| 241 | +Here's the full algorithm: |
| 242 | + |
| 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 |
| 246 | + injected at the top. |
| 247 | +3. Some common `allow` attributes are added for documentation examples at the top. |
| 248 | + |
| 249 | +## Running tests (advanced) |
| 250 | + |
| 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. |
| 256 | + |
| 257 | +~~~console |
| 258 | +# Only run tests containing 'foo' in their name |
| 259 | +$ rustdoc --test lib.rs --test-args 'foo' |
| 260 | + |
| 261 | +# See what's possible when running tests |
| 262 | +$ rustdoc --test lib.rs --test-args '--help' |
| 263 | +~~~ |
| 264 | + |
| 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`. |
| 271 | + |
| 272 | +# Standalone Markdown files |
| 273 | + |
| 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. |
| 277 | + |
| 278 | +There are 4 options to modify the output that Rustdoc creates. |
| 279 | + |
| 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 |
| 285 | + title). |
| 286 | +- `--html-after-content FILE`: includes the contents of `FILE` |
| 287 | + directly before `</body>`, after all the rendered content. |
| 288 | + |
| 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). |
| 293 | + |
| 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. |
0 commit comments