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.

rust
1// DO: third person singular present indicative, ends with period
2/// Returns the length of the string.
3/// Creates a new instance with default settings.
4/// Parses the input and returns the result.
5
6// DON'T: imperative, missing period, or verbose
7/// Return the length of the string
8/// This function creates a new instance with default settings.
9/// Use this to parse the input and get the result back.

Comment Style

Use line comments, not block comments.

rust
1// DO
2/// Summary sentence here.
3///
4/// More details if needed.
5
6// DON'T
7/**
8 * Summary sentence here.
9 *
10 * More details if needed.
11 */

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

Section Headings

Use these exact headings (always plural):

rust
1/// Summary sentence.
2///
3/// # Examples
4///
5/// # Panics
6///
7/// # Errors
8///
9/// # Safety
10///
11/// # Aborts
12///
13/// # Undefined Behavior

rust
1// DO
2/// # Examples
3
4// DON'T
5/// # Example
6/// ## Examples
7/// **Examples:**

Type References

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

rust
1// DO
2/// Returns [`Option<T>`] if the value exists.
3///
4/// [`Option<T>`]: std::option::Option
5
6// DON'T
7/// Returns `Option` if the value exists.
8/// Returns an optional value.

Examples

Every public item should have examples showing usage.

rust
1/// Adds two numbers together.
2///
3/// # Examples
4///
5/// ```
6/// let result = my_crate::add(2, 3);
7/// assert_eq!(result, 5);
8/// ```
9pub fn add(a: i32, b: i32) -> i32 {
10    a + b
11}

For multiple patterns:

rust
1/// Parses a string into a number.
2///
3/// # Examples
4///
5/// Basic usage:
6///
7/// ```
8/// let n: i32 = my_crate::parse("42").unwrap();
9/// assert_eq!(n, 42);
10/// ```
11///
12/// Handling errors:
13///
14/// ```
15/// let result = my_crate::parse::<i32>("not a number");
16/// assert!(result.is_err());
17/// ```

Errors Section

Document what errors can be returned and when.

rust
1/// Reads a file from disk.
2///
3/// # Errors
4///
5/// Returns [`io::Error`] if the file does not exist or cannot be read.
6///
7/// [`io::Error`]: std::io::Error

Panics Section

Document conditions that cause panics.

rust
1/// Divides two numbers.
2///
3/// # Panics
4///
5/// Panics if `divisor` is zero.
6pub fn divide(dividend: i32, divisor: i32) -> i32 {
7    assert!(divisor != 0, "divisor must not be zero");
8    dividend / divisor
9}

Safety Section

Required for unsafe functions.

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

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".