rustdoc

Rust Documentation Conventions (RFC 1574)

Apply these rules when writing doc comments (///) on public Rust items.

Summary Sentence

Every doc comment starts with a single-line summary sentence.

// DO: third person singular present indicative, ends with period
/// Returns the length of the string.
/// Creates a new instance with default settings.
/// Parses the input and returns the result.

// DON'T: imperative, missing period, or verbose
/// Return the length of the string
/// This function creates a new instance with default settings.
/// Use this to parse the input and get the result back.

Comment Style

Use line comments, not block comments.

// DO
/// Summary sentence here.
///
/// More details if needed.

// DON'T
/**
 * Summary sentence here.
 *
 * More details if needed.
 */

Use //! only for crate-level and module-level docs at the top of the file.

Section Headings

Use these exact headings (always plural):

/// Summary sentence.
///
/// # Examples
///
/// # Panics
///
/// # Errors
///
/// # Safety
///
/// # Aborts
///
/// # Undefined Behavior

// DO
/// # Examples

// DON'T
/// # Example
/// ## Examples
/// **Examples:**

Type References

Use full generic forms and link with reference-style markdown.

// DO
/// Returns [`Option<T>`] if the value exists.
///
/// [`Option<T>`]: std::option::Option

// DON'T
/// Returns `Option` if the value exists.
/// Returns an optional value.

Examples

Every public item should have examples showing usage.

/// Adds two numbers together.
///
/// # Examples
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

For multiple patterns:

/// Parses a string into a number.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// let n: i32 = my_crate::parse("42").unwrap();
/// assert_eq!(n, 42);
/// ```
///
/// Handling errors:
///
/// ```
/// let result = my_crate::parse::<i32>("not a number");
/// assert!(result.is_err());
/// ```