Documentation
Use cargo doc to build documentation in target/doc, cargo doc --open
will automatically open it in your web browser.
Use cargo test to run all tests (including documentation tests), and cargo test --doc to only run documentation tests.
These commands will appropriately invoke rustdoc (and rustc) as required.
Doc comments
Doc comments are very useful for big projects that require documentation. When
running rustdoc, these are the comments that get compiled into
documentation. They are denoted by a ///, and support Markdown.
To run the tests, first build the code as a library, then tell rustdoc where
to find the library so it can link it into each doctest program:
$ rustc doc.rs --crate-type lib
$ rustdoc --test --extern doc="libdoc.rlib" doc.rs
Doc attributes
Below are a few examples of the most common #[doc] attributes used with
rustdoc.
inline
Used to inline docs, instead of linking out to separate page.
#[doc(inline)]
pub use bar::Bar;
/// bar docs
pub mod bar {
/// the docs for Bar
pub struct Bar;
}no_inline
Used to prevent linking out to separate page or anywhere.
// Example from libcore/prelude
#[doc(no_inline)]
pub use crate::mem::drop;hidden
Using this tells rustdoc not to include this in documentation:
For documentation, rustdoc is widely used by the community. It's what is used
to generate the std library docs.