Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 23da54d

Browse files
committedJan 21, 2015
Move rustdoc.md into the book
Fixes #21430
1 parent 6869645 commit 23da54d

File tree

3 files changed

+298
-294
lines changed

3 files changed

+298
-294
lines changed
 

‎src/doc/rustdoc.md

Lines changed: 1 addition & 294 deletions
Original file line numberDiff line numberDiff line change
@@ -1,296 +1,3 @@
11
% Rust Documentation
22

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).

‎src/doc/trpl/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
* [Traits](traits.md)
2929
* [Threads](threads.md)
3030
* [Error Handling](error-handling.md)
31+
* [Documentation](documentation.md)
3132
* [III: Advanced Topics](advanced.md)
3233
* [FFI](ffi.md)
3334
* [Unsafe Code](unsafe.md)

‎src/doc/trpl/documentation.md

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
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 - 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

Comments
 (0)
Please sign in to comment.