Comments and Documenting the code

Comments

// Line comments
/* Block comments */

Nested block comments are supported.

πŸ’‘ By convention, try to avoid block comments. Use line comments instead.

Doc Comments

/// Line comments; document the next item
/** Block comments; document the next item */

//! Line comments; document the enclosing item
/*! Block comments; document the enclosing item !*/

Doc comments support Markdown notations. Using cargo doc, the HTML documentation can be generated from these doc comments. Let’s see the difference between the two sets of doc comments.

/// This module contains tests
mod test {
    // ...
}


mod test {
    //! This module contains tests

    // ...
}

As you can see both uses to document the same module. The first comment has been added before the module while the second one has been added inside the module.

πŸ’‘ Only use //! to write crate and module-level documentation, nothing else. When using mod blocks, use /// outside of the block.

Doc Attributes

We can also use doc attributes for documenting the code.

πŸ”Ž An attribute is a general, free-form metadatum that is interpreted according to the name, convention, language and compiler version. Any item declaration may have an attribute applied to it.

Here, for instance, each comment is equivalent to relevant data attributes.

/// Foo
#[doc="Foo"]

//! Foo
#![doc="Foo"]