rustdoc generates reference documentation from Rust source, turning public item names and documentation comments into browsable crate documentation. Good documentation helps library users understand and successfully use an API. section 6.11.2
Build documentation with Cargo, then improve it through focused Rust comments:
- Run `cargo doc`; generated HTML appears under `target/doc`, with the crate index as its landing page. section 6.11.2
- Use `//!` for crate-level documentation and `///` for the item immediately following the comment. section 6.11.2
- Add high-level descriptions, usage examples, and concise explanations to public structs and methods. section 6.11.2
- Use `cargo watch -x doc` to regenerate documentation automatically while editing. section 6.11.2
Documenting a crate
Place `//!` comments at the top of `src/lib.rs`, then show usage with a fenced Rust example: `use linkedlist::LinkedList; let mut animals = LinkedList::new(); animals.append("chicken");`. Document items with `///`, such as `/// Constructs a new, empty [`LinkedList<T>`].`. section 6.11.2
//! # linkedlist crate
//!
//! This crate provides a simple linked list implementation.
//!
//! The crate serves as a teaching example for the book [_Rust Advanced
//! Techniques_](https://www.manning.com/books/idiomatic-rust).
//!
//! ## Example usage
//!
//! ```rust
//! use linkedlist::LinkedList;
//!
//! let mut animals = LinkedList::new();
//! animals.append("chicken");
//! animals.append("ostrich");
//! animals.append("antelope");
//! animals.append("axolotl");
//! animals.append("okapi");
//! ```
Inspect a complete crate-level documentation listing with a description and example usage. section 6.11.2
