docs-rust-conventions

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());
/// ```

Errors Section

Document what errors can be returned and when.

/// Reads a file from disk.
///
/// # Errors
///
/// Returns [`io::Error`] if the file does not exist or cannot be read.
///
/// [`io::Error`]: std::io::Error

Panics Section

Document conditions that cause panics.

/// Divides two numbers.
///
/// # Panics
///
/// Panics if `divisor` is zero.
pub fn divide(dividend: i32, divisor: i32) -> i32 {
    assert!(divisor != 0, "divisor must not be zero");
    dividend / divisor
}

Safety Section

Required for unsafe functions.

/// Dereferences a raw pointer.
///
/// # Safety
///
/// The pointer must be non-null and properly aligned.
/// The pointed-to memory must be valid for the lifetime `'a`.
pub unsafe fn deref<'a, T>(ptr: *const T) -> &'a T {
    &*ptr
}

Module vs Type Docs

• Module docs (//!): high-level summaries, when to use this module
• Type docs (///): comprehensive, self-contained

Some duplication is acceptable.

Language

Use American English spelling: "color" not "colour", "serialize" not "serialise".