How to write documentation

This document explains how to write documentation for the std/core public APIs.

Let's start with some general information:

When to use inline code blocks

Whenever you are talking about a type or anything code related, it should be in a inline code block. As a reminder, a inline code block is created with backticks (`). For example:

This a `Vec` and it has a method `push` which you can call by doing `Vec::push`.

Intra-doc links (you can see the full explanations for the feature here) should be used as much as possible whenever a type is mentioned.

Little note: when you are documenting an item, there is no need to link to it. So, if you write documentation for the String::push_str method, there is no need to link to the push_str method or the String type.

Code blocks

With rustdoc, code blocks are tested (because they are treated as Rust code blocks by default). It allows us to know if the documentation is up to date. As such, please avoid using ignore as much as possible on code blocks! If you want as a language other than Rust, simply set it in the code block tags:

```text
This is not rust code!
```

Some special cases:

  • If the code example cannot be run (when documenting a I/O item for example), use no_run.
  • If it is expected to fail, use should_panic.
  • If it is expected to fail compilation (which be quite rare!), use compile_fail.

You can find more information about code blocks here.

How to write documentation for a module

A module is supposed to contain "similar" items. As such, its documentation is supposed to give an overview and eventually a base to understand what the items it contains are doing.

You can take a look at the f32 module or at the fmt module to see good examples.

How to write documentation for functions/methods

The basic format of each documented methods/functions should roughly look like this:

[explanations]

[example(s)]

Explanations

By explanations we mean that the text should explain what the method and what each of its arguments are for. Let's take this method for example:

pub fn concat_str(&self, s: &str) -> String {
    if s.is_empty() {
        panic!("empty concat string");
    }
    format!("{}{}", self.string, s)
}

The explanation should look like this:

Returns a new [`String`] which contains `&self` content with `s` added at the end.

Panic?

If the function/method can panic in certain circumstances, it must to be mentioned! This explanation needs to be prepended by a Panics title:

# Panics

`concat_str` panics if `s` is empty.

Examples

As for the examples, they have to show the usage of the function/method. Just like the panic section, they need to be prepended by a Example title (plural if there is more than one).

It is better if you use assert*! macros at the end to ensure that the example is working as expected. It also allows the readers to understand more easily what the function is doing (or returning).

# Example

```
let s = MyType::new("hello ");
assert_eq!("hello Georges", s.concat_str("Georges").as_str());
```

How to write documentation for other items

It is mostly the same as for methods and functions except that the examples are (strongly) recommended and not mandatory.

A good example often shows how to create the item.