src/doc/rustdoc.md

   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 # #![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)} }
  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 [sundown][sundown] 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 # Using the Documentation
 107
 108 The web pages generated by rustdoc present the same logical hierarchy that one
 109 writes a library with. Every kind of item (function, struct, etc) has its own
 110 color, and one can always click on a colored type to jump to its
 111 documentation. There is a search bar at the top, which is powered by some
 112 JavaScript and a statically-generated search index. No special web server is
 113 required for the search.
 114
 115 [sundown]: https://github.com/vmg/sundown/
 116
 117 # Testing the Documentation
 118
 119 `rustdoc` has support for testing code examples which appear in the
 120 documentation. This is helpful for keeping code examples up to date with the
 121 source code.
 122
 123 To test documentation, the `--test` argument is passed to rustdoc:
 124
 125 ~~~ {.sh}
 126 rustdoc --test crate.rs
 127 ~~~
 128
 129 ## Defining tests
 130
 131 Rust documentation currently uses the markdown format, and rustdoc treats all
 132 code blocks as testable-by-default unless they carry a language tag of another
 133 language. In order to not run a test over a block of code, the `ignore` string
 134 can be added to the three-backtick form of markdown code block.
 135
 136 ~~~md
 137 ```
 138 // This is a testable code block
 139 ```
 140
 141 ```rust{.example}
 142 // This is rust and also testable
 143 ```
 144
 145 ```ignore
 146 // This is not a testable code block
 147 ```
 148
 149     // This is a testable code block (4-space indent)
 150
 151 ```sh
 152 # this is shell code and not tested
 153 ```
 154 ~~~
 155
 156 You can specify that the test's execution should fail with the `should_fail`
 157 directive.
 158
 159 ~~~md
 160 ```should_fail
 161 // This code block is expected to generate a failure when run
 162 ```
 163 ~~~
 164
 165 You can specify that the code block should be compiled but not run with the
 166 `no_run` directive.
 167
 168 ~~~md
 169 ```no_run
 170 // This code will be compiled but not executed
 171 ```
 172 ~~~
 173
 174 Lastly, you can specify that a code block be compiled as if `--test`
 175 were passed to the compiler using the `test_harness` directive.
 176
 177 ~~~md
 178 ```test_harness
 179 #[test]
 180 fn foo() {
 181     fail!("oops! (will run & register as failure)")
 182 }
 183 ```
 184 ~~~
 185
 186 Rustdoc also supplies some extra sugar for helping with some tedious
 187 documentation examples. If a line is prefixed with `# `, then the line
 188 will not show up in the HTML documentation, but it will be used when
 189 testing the code block (NB. the space after the `#` is required, so
 190 that one can still write things like `#[deriving(Eq)]`).
 191
 192 ~~~md
 193 ```
 194 # /!\ The three following lines are comments, which are usually stripped off by
 195 # the doc-generating tool.  In order to display them anyway in this particular
 196 # case, the character following the leading '#' is not a usual space like in
 197 # these first five lines but a non breakable one.
 198 # // showing 'fib' in this documentation would just be tedious and detracts from
 199 # // what's actually being documented.
 200 # fn fib(n: int) { n + 2 }
 201
 202 spawn(proc() { fib(200); })
 203 ```
 204 ~~~
 205
 206 The documentation online would look like `spawn(proc() { fib(200); })`, but when
 207 testing this code, the `fib` function will be included (so it can compile).
 208
 209 ## Running tests (advanced)
 210
 211 Running tests often requires some special configuration to filter tests, find
 212 libraries, or try running ignored examples. The testing framework that rustdoc
 213 uses is build on crate `test`, which is also used when you compile crates with
 214 rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness
 215 with the `--test-args` flag.
 216
 217 ~~~console
 218 # Only run tests containing 'foo' in their name
 219 $ rustdoc --test lib.rs --test-args 'foo'
 220
 221 # See what's possible when running tests
 222 $ rustdoc --test lib.rs --test-args '--help'
 223 ~~~
 224
 225 When testing a library, code examples will often show how functions are used,
 226 and this code often requires `use`-ing paths from the crate. To accommodate this,
 227 rustdoc will implicitly add `extern crate <crate>;` where `<crate>` is the name of
 228 the crate being tested to the top of each code example. This means that rustdoc
 229 must be able to find a compiled version of the library crate being tested. Extra
 230 search paths may be added via the `-L` flag to `rustdoc`.
 231
 232 # Standalone Markdown files
 233
 234 As well as Rust crates, rustdoc supports rendering pure Markdown files
 235 into HTML and testing the code snippets from them. A Markdown file is
 236 detected by a `.md` or `.markdown` extension.
 237
 238 There are 4 options to modify the output that Rustdoc creates.
 239
 240 - `--markdown-css PATH`: adds a `<link rel="stylesheet">` tag pointing to `PATH`.
 241 - `--markdown-in-header FILE`: includes the contents of `FILE` at the
 242   end of the `<head>...</head>` section.
 243 - `--markdown-before-content FILE`: includes the contents of `FILE`
 244   directly after `<body>`, before the rendered content (including the
 245   title).
 246 - `--markdown-after-content FILE`: includes the contents of `FILE`
 247   directly before `</body>`, after all the rendered content.
 248
 249 All of these can be specified multiple times, and they are output in
 250 the order in which they are specified. The first line of the file must
 251 be the title, prefixed with `%` (e.g. this page has `% Rust
 252 Documentation` on the first line).
 253
 254 Like with a Rust crate, the `--test` argument will run the code
 255 examples to check they compile, and obeys any `--test-args` flags. The
 256 tests are named after the last `#` heading.