2013-12-06 10:29:58 -06:00
|
|
|
|
% Rust Documentation
|
|
|
|
|
|
|
|
|
|
`rustdoc` is the built-in tool for generating documentation. It integrates
|
|
|
|
|
with the compiler to provide accurate hyperlinking between usage of types and
|
|
|
|
|
their documentation. Furthermore, by not using a separate parser, it will
|
|
|
|
|
never reject your valid Rust code.
|
|
|
|
|
|
|
|
|
|
# Creating Documentation
|
|
|
|
|
|
|
|
|
|
Documenting Rust APIs is quite simple. To document a given item, we have "doc
|
|
|
|
|
comments":
|
|
|
|
|
|
|
|
|
|
~~~
|
2014-05-23 00:29:13 -05:00
|
|
|
|
# #![allow(unused_attribute)]
|
2013-12-06 10:29:58 -06:00
|
|
|
|
// the "link" crate attribute is currently required for rustdoc, but normally
|
|
|
|
|
// isn't needed.
|
2014-04-11 22:33:16 -05:00
|
|
|
|
#![crate_id = "universe"]
|
|
|
|
|
#![crate_type="lib"]
|
2013-12-06 10:29:58 -06:00
|
|
|
|
|
|
|
|
|
//! Tools for dealing with universes (this is a doc comment, and is shown on
|
|
|
|
|
//! the crate index page. The ! makes it apply to the parent of the comment,
|
|
|
|
|
//! rather than what follows).
|
|
|
|
|
|
2014-03-08 21:14:07 -06:00
|
|
|
|
# mod workaround_the_outer_function_rustdoc_inserts {
|
2013-12-06 10:29:58 -06:00
|
|
|
|
/// Widgets are very common (this is a doc comment, and will show up on
|
|
|
|
|
/// Widget's documentation).
|
|
|
|
|
pub struct Widget {
|
|
|
|
|
/// All widgets have a purpose (this is a doc comment, and will show up
|
|
|
|
|
/// the field's documentation).
|
2014-05-22 18:57:53 -05:00
|
|
|
|
purpose: String,
|
2013-12-06 10:29:58 -06:00
|
|
|
|
/// Humans are not allowed to understand some widgets
|
|
|
|
|
understandable: bool
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
pub fn recalibrate() {
|
|
|
|
|
//! Recalibrate a pesky universe (this is also a doc comment, like above,
|
|
|
|
|
//! the documentation will be applied to the *parent* item, so
|
|
|
|
|
//! `recalibrate`).
|
|
|
|
|
/* ... */
|
|
|
|
|
}
|
2014-03-08 21:14:07 -06:00
|
|
|
|
# }
|
2013-12-06 10:29:58 -06:00
|
|
|
|
~~~
|
|
|
|
|
|
2014-05-24 13:56:38 -05:00
|
|
|
|
Documentation can also be controlled via the `doc` attribute on items. This is
|
|
|
|
|
implicitly done by the compiler when using the above form of doc comments
|
|
|
|
|
(converting the slash-based comments to `#[doc]` attributes).
|
2014-05-24 13:56:16 -05:00
|
|
|
|
|
|
|
|
|
~~~
|
|
|
|
|
#[doc = "
|
|
|
|
|
Calculates the factorial of a number.
|
|
|
|
|
|
|
|
|
|
Given the input integer `n`, this function will calculate `n!` and return it.
|
|
|
|
|
"]
|
2014-07-02 03:53:30 -05:00
|
|
|
|
pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n - 1)} }
|
2014-05-24 13:56:38 -05:00
|
|
|
|
# fn main() {}
|
2014-05-24 13:56:16 -05:00
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
The `doc` attribute can also be used to control how rustdoc emits documentation
|
|
|
|
|
in some cases.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
// Rustdoc will inline documentation of a `pub use` into this crate when the
|
|
|
|
|
// `pub use` reaches across crates, but this behavior can also be disabled.
|
|
|
|
|
#[doc(no_inline)]
|
|
|
|
|
pub use std::option::Option;
|
2014-05-24 13:56:38 -05:00
|
|
|
|
# fn main() {}
|
2014-05-24 13:56:16 -05:00
|
|
|
|
```
|
|
|
|
|
|
2013-12-10 21:00:24 -06:00
|
|
|
|
Doc comments are markdown, and are currently parsed with the
|
|
|
|
|
[sundown][sundown] library. rustdoc does not yet do any fanciness such as
|
|
|
|
|
referencing other items inline, like javadoc's `@see`. One exception to this
|
2014-03-16 19:12:49 -05:00
|
|
|
|
is that the first paragraph will be used as the "summary" of an item in the
|
2013-12-10 21:00:24 -06:00
|
|
|
|
generated documentation:
|
|
|
|
|
|
|
|
|
|
~~~
|
|
|
|
|
/// A whizbang. Does stuff. (this line is the summary)
|
|
|
|
|
///
|
|
|
|
|
/// Whizbangs are ...
|
|
|
|
|
struct Whizbang;
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
To generate the docs, run `rustdoc universe.rs`. By default, it generates a
|
|
|
|
|
directory called `doc`, with the documentation for `universe` being in
|
2014-02-14 12:10:06 -06:00
|
|
|
|
`doc/universe/index.html`. If you are using other crates with `extern crate`,
|
2013-12-06 10:29:58 -06:00
|
|
|
|
rustdoc will even link to them when you use their types, as long as their
|
|
|
|
|
documentation has already been generated by a previous run of rustdoc, or the
|
|
|
|
|
crate advertises that its documentation is hosted at a given URL.
|
|
|
|
|
|
|
|
|
|
The generated output can be controlled with the `doc` crate attribute, which
|
|
|
|
|
is how the above advertisement works. An example from the `libstd`
|
|
|
|
|
documentation:
|
|
|
|
|
|
|
|
|
|
~~~
|
2014-03-02 05:10:44 -06:00
|
|
|
|
#[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
|
2013-12-06 10:29:58 -06:00
|
|
|
|
html_favicon_url = "http://www.rust-lang.org/favicon.ico",
|
2014-05-21 21:55:39 -05:00
|
|
|
|
html_root_url = "http://doc.rust-lang.org/")];
|
2013-12-06 10:29:58 -06:00
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
The `html_root_url` is the prefix that rustdoc will apply to any references to
|
|
|
|
|
that crate's types etc.
|
|
|
|
|
|
|
|
|
|
rustdoc can also generate JSON, for consumption by other tools, with
|
|
|
|
|
`rustdoc --output-format json`, and also consume already-generated JSON with
|
|
|
|
|
`rustdoc --input-format json`.
|
|
|
|
|
|
2014-06-28 05:35:25 -05:00
|
|
|
|
rustdoc also supports personalizing the output from crates' documentation,
|
|
|
|
|
similar to markdown options.
|
|
|
|
|
|
|
|
|
|
- `--html-in-header FILE`: includes the contents of `FILE` at the
|
|
|
|
|
end of the `<head>...</head>` section.
|
|
|
|
|
- `--html-before-content FILE`: includes the contents of `FILE`
|
|
|
|
|
directly after `<body>`, before the rendered content (including the
|
|
|
|
|
search bar).
|
|
|
|
|
- `--html-after-content FILE`: includes the contents of `FILE`
|
|
|
|
|
after all the rendered content.
|
|
|
|
|
|
2013-12-06 10:29:58 -06:00
|
|
|
|
# Using the Documentation
|
|
|
|
|
|
2014-03-16 19:12:49 -05:00
|
|
|
|
The web pages generated by rustdoc present the same logical hierarchy that one
|
2013-12-06 10:29:58 -06:00
|
|
|
|
writes a library with. Every kind of item (function, struct, etc) has its own
|
|
|
|
|
color, and one can always click on a colored type to jump to its
|
|
|
|
|
documentation. There is a search bar at the top, which is powered by some
|
2014-03-16 19:12:49 -05:00
|
|
|
|
JavaScript and a statically-generated search index. No special web server is
|
2013-12-06 10:29:58 -06:00
|
|
|
|
required for the search.
|
2013-12-10 21:00:24 -06:00
|
|
|
|
|
|
|
|
|
[sundown]: https://github.com/vmg/sundown/
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
|
|
|
|
# Testing the Documentation
|
|
|
|
|
|
|
|
|
|
`rustdoc` has support for testing code examples which appear in the
|
|
|
|
|
documentation. This is helpful for keeping code examples up to date with the
|
|
|
|
|
source code.
|
|
|
|
|
|
|
|
|
|
To test documentation, the `--test` argument is passed to rustdoc:
|
|
|
|
|
|
2014-06-02 05:37:54 -05:00
|
|
|
|
~~~ {.sh}
|
2013-12-22 18:41:37 -06:00
|
|
|
|
rustdoc --test crate.rs
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
## Defining tests
|
|
|
|
|
|
2014-02-15 01:30:10 -06:00
|
|
|
|
Rust documentation currently uses the markdown format, and rustdoc treats all
|
2014-06-02 05:37:54 -05:00
|
|
|
|
code blocks as testable-by-default unless they carry a language tag of another
|
|
|
|
|
language. In order to not run a test over a block of code, the `ignore` string
|
|
|
|
|
can be added to the three-backtick form of markdown code block.
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-06-02 05:37:54 -05:00
|
|
|
|
~~~md
|
2014-05-02 19:56:35 -05:00
|
|
|
|
```
|
|
|
|
|
// This is a testable code block
|
|
|
|
|
```
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-06-02 05:37:54 -05:00
|
|
|
|
```rust{.example}
|
|
|
|
|
// This is rust and also testable
|
|
|
|
|
```
|
|
|
|
|
|
2014-05-02 19:56:35 -05:00
|
|
|
|
```ignore
|
|
|
|
|
// This is not a testable code block
|
|
|
|
|
```
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-05-02 19:56:35 -05:00
|
|
|
|
// This is a testable code block (4-space indent)
|
2014-06-02 05:37:54 -05:00
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
# this is shell code and not tested
|
|
|
|
|
```
|
2014-05-02 19:56:35 -05:00
|
|
|
|
~~~
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-03-08 21:39:01 -06:00
|
|
|
|
You can specify that the test's execution should fail with the `should_fail`
|
|
|
|
|
directive.
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-06-02 05:37:54 -05:00
|
|
|
|
~~~md
|
2014-05-02 19:56:35 -05:00
|
|
|
|
```should_fail
|
|
|
|
|
// This code block is expected to generate a failure when run
|
|
|
|
|
```
|
|
|
|
|
~~~
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-03-08 21:39:01 -06:00
|
|
|
|
You can specify that the code block should be compiled but not run with the
|
|
|
|
|
`no_run` directive.
|
|
|
|
|
|
2014-06-02 05:37:54 -05:00
|
|
|
|
~~~md
|
2014-05-02 19:56:35 -05:00
|
|
|
|
```no_run
|
|
|
|
|
// This code will be compiled but not executed
|
|
|
|
|
```
|
|
|
|
|
~~~
|
2014-03-08 21:39:01 -06:00
|
|
|
|
|
2014-06-19 08:11:18 -05:00
|
|
|
|
Lastly, you can specify that a code block be compiled as if `--test`
|
|
|
|
|
were passed to the compiler using the `test_harness` directive.
|
|
|
|
|
|
|
|
|
|
~~~md
|
|
|
|
|
```test_harness
|
|
|
|
|
#[test]
|
|
|
|
|
fn foo() {
|
|
|
|
|
fail!("oops! (will run & register as failure)")
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
~~~
|
|
|
|
|
|
2013-12-22 18:41:37 -06:00
|
|
|
|
Rustdoc also supplies some extra sugar for helping with some tedious
|
2013-12-28 17:54:56 -06:00
|
|
|
|
documentation examples. If a line is prefixed with `# `, then the line
|
|
|
|
|
will not show up in the HTML documentation, but it will be used when
|
|
|
|
|
testing the code block (NB. the space after the `#` is required, so
|
|
|
|
|
that one can still write things like `#[deriving(Eq)]`).
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-06-02 05:37:54 -05:00
|
|
|
|
~~~md
|
2014-05-02 19:56:35 -05:00
|
|
|
|
```
|
|
|
|
|
# /!\ The three following lines are comments, which are usually stripped off by
|
|
|
|
|
# the doc-generating tool. In order to display them anyway in this particular
|
|
|
|
|
# case, the character following the leading '#' is not a usual space like in
|
|
|
|
|
# these first five lines but a non breakable one.
|
|
|
|
|
# // showing 'fib' in this documentation would just be tedious and detracts from
|
|
|
|
|
# // what's actually being documented.
|
|
|
|
|
# fn fib(n: int) { n + 2 }
|
|
|
|
|
|
|
|
|
|
spawn(proc() { fib(200); })
|
|
|
|
|
```
|
|
|
|
|
~~~
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-04-04 19:32:46 -05:00
|
|
|
|
The documentation online would look like `spawn(proc() { fib(200); })`, but when
|
2013-12-22 18:41:37 -06:00
|
|
|
|
testing this code, the `fib` function will be included (so it can compile).
|
|
|
|
|
|
|
|
|
|
## Running tests (advanced)
|
|
|
|
|
|
|
|
|
|
Running tests often requires some special configuration to filter tests, find
|
|
|
|
|
libraries, or try running ignored examples. The testing framework that rustdoc
|
2014-02-13 19:49:11 -06:00
|
|
|
|
uses is build on crate `test`, which is also used when you compile crates with
|
2013-12-22 18:41:37 -06:00
|
|
|
|
rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness
|
|
|
|
|
with the `--test-args` flag.
|
|
|
|
|
|
2014-06-02 05:37:54 -05:00
|
|
|
|
~~~console
|
2014-05-02 19:56:35 -05:00
|
|
|
|
# Only run tests containing 'foo' in their name
|
2014-03-08 21:14:07 -06:00
|
|
|
|
$ rustdoc --test lib.rs --test-args 'foo'
|
2013-12-22 18:41:37 -06:00
|
|
|
|
|
2014-05-02 19:56:35 -05:00
|
|
|
|
# See what's possible when running tests
|
2014-03-08 21:14:07 -06:00
|
|
|
|
$ rustdoc --test lib.rs --test-args '--help'
|
2013-12-22 18:41:37 -06:00
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
When testing a library, code examples will often show how functions are used,
|
2014-03-16 19:12:49 -05:00
|
|
|
|
and this code often requires `use`-ing paths from the crate. To accommodate this,
|
2014-02-14 12:10:06 -06:00
|
|
|
|
rustdoc will implicitly add `extern crate <crate>;` where `<crate>` is the name of
|
2013-12-22 18:41:37 -06:00
|
|
|
|
the crate being tested to the top of each code example. This means that rustdoc
|
|
|
|
|
must be able to find a compiled version of the library crate being tested. Extra
|
|
|
|
|
search paths may be added via the `-L` flag to `rustdoc`.
|
2014-03-06 21:31:41 -06:00
|
|
|
|
|
|
|
|
|
# Standalone Markdown files
|
|
|
|
|
|
|
|
|
|
As well as Rust crates, rustdoc supports rendering pure Markdown files
|
|
|
|
|
into HTML and testing the code snippets from them. A Markdown file is
|
|
|
|
|
detected by a `.md` or `.markdown` extension.
|
|
|
|
|
|
|
|
|
|
There are 4 options to modify the output that Rustdoc creates.
|
2014-03-08 21:14:07 -06:00
|
|
|
|
|
2014-03-06 21:31:41 -06:00
|
|
|
|
- `--markdown-css PATH`: adds a `<link rel="stylesheet">` tag pointing to `PATH`.
|
2014-06-28 05:35:25 -05:00
|
|
|
|
- `--html-in-header FILE`: includes the contents of `FILE` at the
|
2014-03-06 21:31:41 -06:00
|
|
|
|
end of the `<head>...</head>` section.
|
2014-06-28 05:35:25 -05:00
|
|
|
|
- `--html-before-content FILE`: includes the contents of `FILE`
|
2014-03-06 21:31:41 -06:00
|
|
|
|
directly after `<body>`, before the rendered content (including the
|
|
|
|
|
title).
|
2014-06-28 05:35:25 -05:00
|
|
|
|
- `--html-after-content FILE`: includes the contents of `FILE`
|
2014-03-06 21:31:41 -06:00
|
|
|
|
directly before `</body>`, after all the rendered content.
|
|
|
|
|
|
|
|
|
|
All of these can be specified multiple times, and they are output in
|
2014-06-28 05:35:25 -05:00
|
|
|
|
the order in which they are specified. The first line of the file being rendered must
|
2014-03-06 21:31:41 -06:00
|
|
|
|
be the title, prefixed with `%` (e.g. this page has `% Rust
|
|
|
|
|
Documentation` on the first line).
|
|
|
|
|
|
|
|
|
|
Like with a Rust crate, the `--test` argument will run the code
|
|
|
|
|
examples to check they compile, and obeys any `--test-args` flags. The
|
|
|
|
|
tests are named after the last `#` heading.
|