2.17 Comments and Documentation
Rust supports several forms of comments, including special syntax for generating documentation.
2.17.1 Regular Comments
// Single-line comment
: Extends to the end of the line./* Multi-line comment */
: Can span multiple lines. These can be nested.
#![allow(unused)] fn main() { // Calculate the square of a number fn square(x: i32) -> i32 { /* This function takes an integer, multiplies it by itself, and returns the result. */ x * x } }
2.17.2 Documentation Comments (rustdoc
)
Rust has built-in support for documentation generation via the rustdoc
tool, which processes special documentation comments written in Markdown.
/// Doc comment for the item following it
: Used for functions, structs, modules, etc.//! Doc comment for the enclosing item
: Used inside a module or crate root (lib.rs
ormain.rs
) to document the module/crate itself.
//! This module provides utility functions for string manipulation. /// Reverses a given string slice. /// /// # Examples /// /// ``` /// let original = "hello"; /// # // We might hide the module path in the rendered docs for simplicity, /// # // but it's needed here if `reverse` is in `string_utils`. /// # mod string_utils { pub fn reverse(s: &str) -> String { s.chars().rev().collect() } } /// let reversed = string_utils::reverse(original); /// assert_eq!(reversed, "olleh"); /// ``` /// /// # Panics /// This function might panic if memory allocation fails (very unlikely). pub fn reverse(s: &str) -> String { s.chars().rev().collect() } // (Module content continues...) // Need a main function for the doctest harness to work correctly fn main() { mod string_utils { pub fn reverse(s: &str) -> String { s.chars().rev().collect() } } let original = "hello"; let reversed = string_utils::reverse(original); assert_eq!(reversed, "olleh"); }
Running cargo doc
builds the documentation for your project and its dependencies as HTML files, viewable in a web browser. Code examples within ///
comments (inside triple backticks
) are compiled and run as tests by cargo test
, ensuring documentation stays synchronized with the code.
Multi-line doc comments /** ... */
(for following item) and /*! ... */
(for enclosing item) also exist but are less common than ///
and //!
.