Comment your Rust Code

Introduction

This post explains how to properly comment you Rust code.

Add Documentation to your Public APIs

/// This is a documentation comment

Documentation comments can be used to generate public HTML documentation. So these are ideal to document your public Structs, Methods and Functions. Also Documentation support markdown formats. Explain Panics, Errors, Examples of your code and whether your code is Safe or Unsafe.

Cargo runs your Doc Examples

To ensure your code is up to date, Cargo test will run examples in your documentation. This is really awesome.

Use Regular Comments for Code Internals

// This is a regular comment

Use regular comments to describe your code’s internals. These would not be included in the generated HTML file.