Rust comments

Regular Comments

// inline comment

/* multiline
 * comment
 */

Annotation Comments

Variable assignments can be annotated

// This number is used because...
let magic_number = 123;

Doc Comments

Generate/View Docs

cargo doc --open  # build, and view docs (current project, and it's dependencies)

Basics

doc-comments are written in markdown, and code-blocks default to rust as the language.
assertions written in doc-comments are run with your test-suite.

//! # My Module (doc-comment for enclosing item)
//!
//! This module does foo, and bar, and baz.
//! (can be used for functions, but not idiomatic)
//! (often used for crates)


/// Feeds the cat  (doc-comment for following-item)
///
/// # Examples
///
/// ```
/// let name = "mycat";
/// let success = feed(name);
/// assert!(success);
/// ```
fn feed_cat(name: &str) -> bool {
    println!("hi")
}

Common Headers

It's customary to write the following headers:

Examples	sample of use
Panics	scenarios when this method panics
Errors	the error types that may be returned
Safety	if function is unsafe, why