From 40d369ac6a5ace63d00acbeafddf61f18e046cac Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 8 Dec 2014 13:13:09 -0500 Subject: [PATCH 1/2] API comment conventions --- text/0000-api-comment-conventions.md | 125 +++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 text/0000-api-comment-conventions.md diff --git a/text/0000-api-comment-conventions.md b/text/0000-api-comment-conventions.md new file mode 100644 index 00000000000..edd7cdf878d --- /dev/null +++ b/text/0000-api-comment-conventions.md @@ -0,0 +1,125 @@ +- Start Date: 2014-12-08 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary + +This is a conventions RFC, providing guidance on providing API documentation +for Rust projects, including the Rust language itself. + +# Motivation + +Documentation is an extremely important part of any project. It's important +that we have consistency in our documentation. + +For the most part, the RFC proposes guidelines that are already followed today, +but it tries to motivate and clarify them. + +# Detailed design + +There are a number of indivudal guidelines: + +## Use line comments + +Avoid block comments. Use line comments instead: + +```rust +// Wait for the main task to return, and set the process error code +// appropriately. +``` + +Instead of: + +```rust +/* + * Wait for the main task to return, and set the process error code + * appropriately. + */ +``` + +Only use inner doc comments //! to write crate and module-level documentation, nothing else. + +## Formatting + +The first line in any doc comment should be a single-line short sentence +providing a summary of the code. This line is used as a summary description +throughout Rustdoc's output, so it's a good idea to keep it short. + +All doc comments, including the summary line, should begin with a capital +letter and end with a period, question mark, or exclamation point. Prefer full +sentences to fragments. + +The summary line should be written in third person singular present indicative +form. Basically, this means write "Returns" instead of "Return". + +## Using Markdown + +Within doc comments, use Markdown to format your documentation. + +Use top level headings # to indicate sections within your comment. Common headings: + +* Examples +* Panics +* Failure + +Even if you only include one example, use the plural form: "Examples" rather +than "Example". Future tooling is easier this way. + +Use graves (`) to denote a code fragment within a sentence. + +Use triple graves (```) to write longer examples, like this: + + This code does something cool. + + ```rust + let x = foo(); + x.bar(); + ``` + +When appropriate, make use of Rustdoc's modifiers. Annotate triple grave blocks with +the appropriate formatting directive. While they default to Rust in Rustdoc, prefer +being explicit, so that it highlights syntax in places that do not, like GitHub. + + ```rust + println!("Hello, world!"); + ``` + + ```ruby + puts "Hello" + ``` + +Rustdoc is able to test all Rust examples embedded inside of documentation, so +it's important to mark what is not Rust so your tests don't fail. + +References and citation should be linked inline. Prefer + +``` +[some paper](http://www.foo.edu/something.pdf) +``` + +to + +``` +some paper[1] + +1: http://www.foo.edu/something.pdf +``` + +## English + +All documentation is standardized on American English, with regards to +spelling, grammar, and punctuation conventions. Language changes over time, +so this doesn't mean that there is always a correct answer to every grammar +question, but there is often some kind of formal consensus. + +# Drawbacks + +None. + +# Alternatives + +Not having documentation guidelines. + +# Unresolved questions + +None. From 1f4cf0e02bb2fe3a0340cacecde9e22b8d35391d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Sun, 8 Feb 2015 18:14:53 -0500 Subject: [PATCH 2/2] Update per feedback --- text/0000-api-comment-conventions.md | 41 +++++++++++++++++++++------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/text/0000-api-comment-conventions.md b/text/0000-api-comment-conventions.md index edd7cdf878d..353d585b0a1 100644 --- a/text/0000-api-comment-conventions.md +++ b/text/0000-api-comment-conventions.md @@ -17,7 +17,9 @@ but it tries to motivate and clarify them. # Detailed design -There are a number of indivudal guidelines: +There are a number of individual guidelines. Most of these guidelines are for +any Rust project, but some are specific to documenting `rustc` itself and the +standard library. These are called out specifically in the text itself. ## Use line comments @@ -37,7 +39,25 @@ Instead of: */ ``` -Only use inner doc comments //! to write crate and module-level documentation, nothing else. +Only use inner doc comments //! to write crate and module-level documentation, +nothing else. When using `mod` blocks, prefer `///` outside of the block: + +```rust +/// This module contains tests +mod test { + // ... +} +``` + +over + +```rust +mod test { + //! This module contains tests + + // ... +} +``` ## Formatting @@ -45,9 +65,8 @@ The first line in any doc comment should be a single-line short sentence providing a summary of the code. This line is used as a summary description throughout Rustdoc's output, so it's a good idea to keep it short. -All doc comments, including the summary line, should begin with a capital -letter and end with a period, question mark, or exclamation point. Prefer full -sentences to fragments. +All doc comments, including the summary line, should be property punctuated. +Prefer full sentences to fragments. The summary line should be written in third person singular present indicative form. Basically, this means write "Returns" instead of "Return". @@ -91,22 +110,24 @@ being explicit, so that it highlights syntax in places that do not, like GitHub. Rustdoc is able to test all Rust examples embedded inside of documentation, so it's important to mark what is not Rust so your tests don't fail. -References and citation should be linked inline. Prefer +References and citation should be linked 'reference style.' Prefer ``` -[some paper](http://www.foo.edu/something.pdf) +[some paper][something] + +[something]: http://www.foo.edu/something.pdf) ``` to ``` -some paper[1] - -1: http://www.foo.edu/something.pdf +[some paper][http://www.foo.edu/something.pdf] ``` ## English +This section applies to `rustc` and the standard library. + All documentation is standardized on American English, with regards to spelling, grammar, and punctuation conventions. Language changes over time, so this doesn't mean that there is always a correct answer to every grammar