en/src/comments-docs.md
Every program requires comments:
// Line comment, which goes to the end of the line/* Block comment, which goes to the end of the closing delimiter */fn main() {
// This is an example of a line comment
// There are two slashes at the beginning of the line
// And nothing written inside these will be read by the compiler
// println!("Hello, world!");
// Run it. See? Now try deleting the two slashes, and run it again.
/*
* This is another type of comment, a block comment. In general,
* line comments are the recommended comment style. But
* block comments are extremely useful for temporarily disabling
* chunks of code. /* Block comments can be /* nested, */ */
* so it takes only a few keystrokes to comment out everything
* in this main() function. /*/*/* Try it yourself! */*/*/
*/
/*
Note: The previous column of `*` was entirely for style. There's
no actual need for it.
*/
}
/* Make it work, only using comments! */
fn main() {
todo!();
unimplemented!();
assert_eq!(6, 5 + 3 + 2 + 1 )
}
Markdown
/// Generate library docs for the following item//! Generate library docs for the eclosing itemBefore starting, we need to create a new package for practice: cargo new --lib doc-comments.
///Add docs for function add_one
// in lib.rs
/// Add one to the given value and return the value
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
x + 1
}
We can use cargo doc --open to generate html files and open them in the browser.
/** ... */Add docs for function add_two:
/** Add two to the given value and return a new value
# Examples
let arg = 5;
let answer = my_crate::add_two(arg);
assert_eq!(7, answer);
*/
pub fn add_two(x: i32) -> i32 {
x + 2
}
We can also add doc comments for our crates and modules.
Firstly, let's add some doc comments for our library crate:
Note: We must place crates and module comments at the top of crate root or module file.
//! # Doc comments
//!
//! A library for showing how to use doc comments
// in lib.rs
pub mod compute;
You can also use block comments to achieve this:
/*! # Doc comments
A library for showing how to use doc comments */
Next, create a new module file src/compute.rs, and add following comments to it:
//! //! Do some complicated arithmetic that you can't do by yourself
// in compute.rs
Then run cargo doc --open and see the results.
The doc comments of add_one and add_two contain two example code blocks.
The examples can not only demonstrate how to use your library, but also running as test with cargo test command.
cargo test to get following result:running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Doc-tests doc-comments
running 2 tests
test src/lib.rs - add_one (line 11) ... ok
test src/lib.rs - add_two (line 26) ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.55s
src/compute.rs and make the cargo test passed.You can only modify the comments, DON'T modify
fn div
// in src/compute.rs
/// # Panics
///
/// The function panics if the second argument is zero.
///
/// ```rust,should_panic
/// // panics on division by zero
/// doc_comments::compute::div(10, 0);
/// ```
pub fn div(a: i32, b: i32) -> i32 {
if b == 0 {
panic!("Divide-by-zero error");
}
a / b
}
Add following code to src/compute.rs ,
// in src/compute.rs
/// ```
/// # fn try_main() -> Result<(), String> {
/// # let res = doc_comments::compute::try_div(10, 0)?;
/// # Ok(()) // returning from try_main
/// # }
/// # fn main() {
/// # try_main().unwrap();
/// #
/// # }
/// ```
pub fn try_div(a: i32, b: i32) -> Result<i32, String> {
if b == 0 {
Err(String::from("Divide-by-zero"))
} else {
Ok(a / b)
}
}
and modify this code to achieve two goals:
cargo doc --openrunning 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Doc-tests doc-comments
running 4 tests
test src/compute.rs - compute::div (line 7) ... ok
test src/lib.rs - add_two (line 27) ... ok
test src/lib.rs - add_one (line 11) ... ok
test src/compute.rs - compute::try_div (line 20) ... ok
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.51s
Rust provide a very powerful feature for us, that is code navigation in doc comments.
Add following code to src/lib.rs:
// in lib.rs
/// Add three to the given value and return a [`Option`] type
pub fn add_three(x: i32) -> Option<i32> {
Some(x + 3)
}
Besides jump into the standard library, you can also jump to another module in the package.
// in lib.rs
mod a {
/// Add four to the given value and return a [`Option`] type
/// [`crate::MySpecialFormatter`]
pub fn add_four(x: i32) -> Option<i32> {
Some(x + 4)
}
}
struct MySpecialFormatter;
Below are a few examples of the most common #[doc] attributes used with rustdoc.
inlineUsed to inline docs, instead of linking out to separate page.
#[doc(inline)]
pub use bar::Bar;
/// bar docs
mod bar {
/// the docs for Bar
pub struct Bar;
}
no_inlineUsed to prevent linking out to separate page or anywhere.
// Example from libcore/prelude
#[doc(no_inline)]
pub use crate::mem::drop;
hiddenUsing this tells rustdoc not to include this in documentation:
// Example from the futures-rs library
#[doc(hidden)]
pub use self::async_await::*;
For documentation, rustdoc is widely used by the community. It's what is used to generate the std library docs.
The full code of package doc-comments is here.