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.