What does //! stand for in rust comments?

I cloned a repo which uses both /// and //! for comments. I understand /// generates documentation via cargo doc, but what does //! do? When should I use it?

//! is a documentation comment that applies to the item that it is inside of, instead of the item that comes after it. It's commonly used for documenting a module, and it's the only way to document the top-level module of a crate.

For example, this:

mod foo {
    //! The foo module
    ...
}

Is equivalent to this:

/// The foo module
mod foo {
    ...
}
2 Likes

And here's an example of using it to document an entire module file: std::alloc documentation and the corresponding source.

1 Like