Writing Documentation ​

Generating Documentation ​

Generate Rust documentation using rustdoc which is provided with cargo.

cargo doc        # Creates documentation for your crate
cargo doc --open # Creates and serves the documentation

cargo doc        # Creates documentation for your crate
cargo doc --open # Creates and serves the documentation

Documentation Comments ​

Use either /// or //! to specify that the comments are meant for documentation.

• The /// comment style should be used before the item being commented, and is used for functions, structs, and enums.

• The //! comment style should be used after the item being commented, and is used for to document modules.

• The /// comment style should be used before the item being commented, and is used for functions, structs, and enums.

• The //! comment style should be used after the item being commented, and is used for to document modules.

Good documentation blocks have three components:

1. A brief explanation of what the item does
2. An inline code block that doubles as a test and illustrative example of how to use the item. See Documentation Tests.
3. Situations where the function/method will panic

And the following sections:

• Arguments: A description of each argument and any non-obvious constraints.
• Returns: If the return type needs interpretation, then add it here.
• Examples: Provide at least one example of how to use the function. Consider using a
• Errors: If the function returns a Result, describe the scenarios that will causes errors.
• Panics: If the function panics, describe the scenarios that will cause them.

RESOURCES ​

• Rustdoc Book: How to write documentation
• Guide on how to write documentation for a Rust crate