Documentation Guidelines for Rust APIs

• Follow Splinter’s general documentation guidelines and capitalization guidelines.

• Provide a crate-level overview (with //! comments) that summarizes the purpose of the crate.

• Include a module-level summary (with //! comments), using this guideline from rustlang RFC 1574:

  “… module-level documentation should show a high-level summary of everything in the module, and each type should document itself fully. It is okay if there is some small amount of duplication here.”

• For modules, traits, structs, etc., include a short summary sentence that starts with a noun instead of a verb. Don’t repeat the module, trait, or struct name in the summary sentence. For example, say “Traits for …” not “Contains traits for …”.

• For methods, include a short summary sentence that starts with a third-person singular verb (“Returns” instead of “Return”). Don’t start with “This method”; instead, go straight to the verb.

• You can use Markdown to format doc comments (headings, lists, code, etc.) See these rust-lang tips on using Markdown.

• For doc comment basics, see The Rust Book, Making Useful Documentation Comments.

• For more best practices, see the Google developer documentation style guide for advice on API reference code comments.