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 // the "link" crate attribute is currently required for rustdoc, but normally
  15 // isn't needed.
  16 #![crate_id = "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 # mod workaround_the_outer_function_rustdoc_inserts {
  24 /// Widgets are very common (this is a doc comment, and will show up on
  25 /// Widget's documentation).
  26 pub struct Widget {
  27         /// All widgets have a purpose (this is a doc comment, and will show up
  28         /// the field's documentation).
  29         purpose: ~str,
  30         /// Humans are not allowed to understand some widgets
  31         understandable: bool
  32 }
  33
  34 pub fn recalibrate() {
  35         //! Recalibrate a pesky universe (this is also a doc comment, like above,
  36         //! the documentation will be applied to the *parent* item, so
  37         //! `recalibrate`).
  38         /* ... */
  39 }
  40 # }
  41 ~~~
  42
  43 Doc comments are markdown, and are currently parsed with the
  44 [sundown][sundown] library. rustdoc does not yet do any fanciness such as
  45 referencing other items inline, like javadoc's `@see`. One exception to this
  46 is that the first paragraph will be used as the "summary" of an item in the
  47 generated documentation:
  48
  49 ~~~
  50 /// A whizbang. Does stuff. (this line is the summary)
  51 ///
  52 /// Whizbangs are ...
  53 struct Whizbang;
  54 ~~~
  55
  56 To generate the docs, run `rustdoc universe.rs`. By default, it generates a
  57 directory called `doc`, with the documentation for `universe` being in
  58 `doc/universe/index.html`. If you are using other crates with `extern crate`,
  59 rustdoc will even link to them when you use their types, as long as their
  60 documentation has already been generated by a previous run of rustdoc, or the
  61 crate advertises that its documentation is hosted at a given URL.
  62
  63 The generated output can be controlled with the `doc` crate attribute, which
  64 is how the above advertisement works. An example from the `libstd`
  65 documentation:
  66
  67 ~~~
  68 #[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
  69       html_favicon_url = "http://www.rust-lang.org/favicon.ico",
  70       html_root_url = "http://static.rust-lang.org/doc/master")];
  71 ~~~
  72
  73 The `html_root_url` is the prefix that rustdoc will apply to any references to
  74 that crate's types etc.
  75
  76 rustdoc can also generate JSON, for consumption by other tools, with
  77 `rustdoc --output-format json`, and also consume already-generated JSON with
  78 `rustdoc --input-format json`.
  79
  80 # Using the Documentation
  81
  82 The web pages generated by rustdoc present the same logical hierarchy that one
  83 writes a library with. Every kind of item (function, struct, etc) has its own
  84 color, and one can always click on a colored type to jump to its
  85 documentation. There is a search bar at the top, which is powered by some
  86 JavaScript and a statically-generated search index. No special web server is
  87 required for the search.
  88
  89 [sundown]: https://github.com/vmg/sundown/
  90
  91 # Testing the Documentation
  92
  93 `rustdoc` has support for testing code examples which appear in the
  94 documentation. This is helpful for keeping code examples up to date with the
  95 source code.
  96
  97 To test documentation, the `--test` argument is passed to rustdoc:
  98
  99 ~~~ {.notrust}
 100 rustdoc --test crate.rs
 101 ~~~
 102
 103 ## Defining tests
 104
 105 Rust documentation currently uses the markdown format, and rustdoc treats all
 106 code blocks as testable-by-default. In order to not run a test over a block of
 107 code, the `ignore` string can be added to the three-backtick form of markdown
 108 code block.
 109
 110 ~~~notrust
 111 ```
 112 // This is a testable code block
 113 ```
 114
 115 ```ignore
 116 // This is not a testable code block
 117 ```
 118
 119     // This is a testable code block (4-space indent)
 120 ~~~
 121
 122 You can specify that the test's execution should fail with the `should_fail`
 123 directive.
 124
 125 ~~~notrust
 126 ```should_fail
 127 // This code block is expected to generate a failure when run
 128 ```
 129 ~~~
 130
 131 You can specify that the code block should be compiled but not run with the
 132 `no_run` directive.
 133
 134 ~~~notrust
 135 ```no_run
 136 // This code will be compiled but not executed
 137 ```
 138 ~~~
 139
 140 Rustdoc also supplies some extra sugar for helping with some tedious
 141 documentation examples. If a line is prefixed with `# `, then the line
 142 will not show up in the HTML documentation, but it will be used when
 143 testing the code block (NB. the space after the `#` is required, so
 144 that one can still write things like `#[deriving(Eq)]`).
 145
 146 ~~~notrust
 147 ```
 148 # /!\ The three following lines are comments, which are usually stripped off by
 149 # the doc-generating tool.  In order to display them anyway in this particular
 150 # case, the character following the leading '#' is not a usual space like in
 151 # these first five lines but a non breakable one.
 152 # // showing 'fib' in this documentation would just be tedious and detracts from
 153 # // what's actually being documented.
 154 # fn fib(n: int) { n + 2 }
 155
 156 spawn(proc() { fib(200); })
 157 ```
 158 ~~~
 159
 160 The documentation online would look like `spawn(proc() { fib(200); })`, but when
 161 testing this code, the `fib` function will be included (so it can compile).
 162
 163 ## Running tests (advanced)
 164
 165 Running tests often requires some special configuration to filter tests, find
 166 libraries, or try running ignored examples. The testing framework that rustdoc
 167 uses is build on crate `test`, which is also used when you compile crates with
 168 rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness
 169 with the `--test-args` flag.
 170
 171 ~~~ {.notrust}
 172 # Only run tests containing 'foo' in their name
 173 $ rustdoc --test lib.rs --test-args 'foo'
 174
 175 # See what's possible when running tests
 176 $ rustdoc --test lib.rs --test-args '--help'
 177 ~~~
 178
 179 When testing a library, code examples will often show how functions are used,
 180 and this code often requires `use`-ing paths from the crate. To accommodate this,
 181 rustdoc will implicitly add `extern crate <crate>;` where `<crate>` is the name of
 182 the crate being tested to the top of each code example. This means that rustdoc
 183 must be able to find a compiled version of the library crate being tested. Extra
 184 search paths may be added via the `-L` flag to `rustdoc`.
 185
 186 # Standalone Markdown files
 187
 188 As well as Rust crates, rustdoc supports rendering pure Markdown files
 189 into HTML and testing the code snippets from them. A Markdown file is
 190 detected by a `.md` or `.markdown` extension.
 191
 192 There are 4 options to modify the output that Rustdoc creates.
 193
 194 - `--markdown-css PATH`: adds a `<link rel="stylesheet">` tag pointing to `PATH`.
 195 - `--markdown-in-header FILE`: includes the contents of `FILE` at the
 196   end of the `<head>...</head>` section.
 197 - `--markdown-before-content FILE`: includes the contents of `FILE`
 198   directly after `<body>`, before the rendered content (including the
 199   title).
 200 - `--markdown-after-content FILE`: includes the contents of `FILE`
 201   directly before `</body>`, after all the rendered content.
 202
 203 All of these can be specified multiple times, and they are output in
 204 the order in which they are specified. The first line of the file must
 205 be the title, prefixed with `%` (e.g. this page has `% Rust
 206 Documentation` on the first line).
 207
 208 Like with a Rust crate, the `--test` argument will run the code
 209 examples to check they compile, and obeys any `--test-args` flags. The
 210 tests are named after the last `#` heading.