% 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":
-
-~~~
-# #![allow(unused_attribute)]
-// the "link" crate attribute is currently required for rustdoc, but normally
-// isn't needed.
-#![crate_id = "universe"]
-#![crate_type="lib"]
-
-//! 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).
-
-# mod workaround_the_outer_function_rustdoc_inserts {
-/// 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).
- purpose: String,
- /// 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`).
- /* ... */
-}
-# }
-~~~
-
-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).
-
-~~~
-#[doc = "
-Calculates the factorial of a number.
-
-Given the input integer `n`, this function will calculate `n!` and return it.
-"]
-pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n - 1)} }
-# fn main() {}
-~~~
-
-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;
-# fn main() {}
-```
-
-Doc comments are markdown, and are currently parsed with the
-[hoedown][hoedown] library. rustdoc does not yet do any fanciness such as
-referencing other items inline, like javadoc's `@see`. One exception to this
-is that the first paragraph will be used as the "summary" of an item in the
-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
-`doc/universe/index.html`. If you are using other crates with `extern crate`,
-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:
-
-~~~
-#[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
- html_favicon_url = "http://www.rust-lang.org/favicon.ico",
- html_root_url = "http://doc.rust-lang.org/")];
-~~~
-
-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`.
-
-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.
-
-# Using the Documentation
-
-The web pages generated by rustdoc present the same logical hierarchy that one
-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
-JavaScript and a statically-generated search index. No special web server is
-required for the search.
-
-[hoedown]: https://github.com/hoedown/hoedown
-
-# 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:
-
-~~~ {.sh}
-rustdoc --test crate.rs
-~~~
-
-## Defining tests
-
-Rust documentation currently uses the markdown format, and rustdoc treats all
-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.
-
-~~~md
-```
-// This is a testable code block
-```
-
-```rust{.example}
-// This is rust and also testable
-```
-
-```ignore
-// This is not a testable code block
-```
-
- // This is a testable code block (4-space indent)
-
-```sh
-# this is shell code and not tested
-```
-~~~
-
-You can specify that the test's execution should fail with the `should_fail`
-directive.
-
-~~~md
-```should_fail
-// This code block is expected to generate a panic when run
-```
-~~~
-
-You can specify that the code block should be compiled but not run with the
-`no_run` directive.
-
-~~~md
-```no_run
-// This code will be compiled but not executed
-```
-~~~
-
-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() {
- panic!("oops! (will run & register as a failed test)")
-}
-```
-~~~
-
-Rustdoc also supplies some extra sugar for helping with some tedious
-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 `#[derive(Eq)]`).
-
-~~~md
-```
-# /!\ 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(move || { fib(200); })
-```
-~~~
-
-The documentation online would look like `spawn(move || { fib(200); })`, but when
-testing this code, the `fib` function will be included (so it can compile).
-
-Rustdoc will automatically add a `main()` wrapper around your code, and in the right
-place. For example:
-
-```
-/// ```
-/// use std::rc::Rc;
-///
-/// let five = Rc::new(5);
-/// ```
-# fn foo() {}
-```
-
-This will end up testing:
-
-```
-fn main() {
- use std::rc::Rc;
- let five = Rc::new(5);
-}
-```
-
-Here's the full algorithm:
-
-1. Given a code block, if it does not contain `fn main`, it is wrapped in `fn main() { your_code }`
-2. Given that result, if it contains no `extern crate` directives but it also
- contains the name of the crate being tested, then `extern crate <name>` is
- injected at the top.
-3. Some common `allow` attributes are added for documentation examples at the top.
-
-## 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
-uses is built on crate `test`, which is also used when you compile crates with
-rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness
-with the `--test-args` flag.
-
-~~~console
-# Only run tests containing 'foo' in their name
-$ rustdoc --test lib.rs --test-args 'foo'
-
-# See what's possible when running tests
-$ rustdoc --test lib.rs --test-args '--help'
-~~~
-
-When testing a library, code examples will often show how functions are used,
-and this code often requires `use`-ing paths from the crate. To accommodate this,
-rustdoc will implicitly add `extern crate <crate>;` where `<crate>` is the name of
-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`.
-
-# 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.
-
-- `--markdown-css PATH`: adds a `<link rel="stylesheet">` tag pointing to `PATH`.
-- `--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
- title).
-- `--html-after-content FILE`: includes the contents of `FILE`
- directly before `</body>`, after all the rendered content.
-
-All of these can be specified multiple times, and they are output in
-the order in which they are specified. The first line of the file being rendered must
-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.
+This has been moved [into the book](book/documentation.html).
projects / rust.git / blobdiff