Outer documentation attaches crate-level or module-level documentation to the surrounding scope. In Rust, comments beginning with //! document the outer scope, while /// documents the next item. section 6.11.2
Documenting a crate
Place top-level documentation at the beginning of src/lib.rs: //! # linkedlist crate //! //! This crate provides a simple linked list implementation. //! //! ## Example usage //! //! ```rust //! use linkedlist::LinkedList; //! let mut animals = LinkedList::new(); //! animals.append("chicken"); //! ``` The rendered crate page gives users a starting point and a runnable usage example. section 6.11.2
Use outer documentation when you need to:
- Describe a crate’s purpose and its primary entry point. section 6.11.2
- Include examples that rustdoc turns into integration tests. section 6.11.2
- Regenerate documentation during editing with cargo watch -x doc. 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 the complete crate-level //! example, including its rendered usage code. section 6.11.2
