|
1 | 1 | % Rust Documentation |
2 | 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 - 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. |
| 3 | +This has been moved [into the book](book/documentation.html). |
0 commit comments