From efa2e50e3a489e9ef2350a01066980d15bcd602f Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 31 Mar 2016 18:22:15 -0400 Subject: [PATCH 01/14] Rough draft --- ...0000-more-api-documentation-conventions.md | 266 ++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 text/0000-more-api-documentation-conventions.md diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md new file mode 100644 index 00000000000..47b52584f43 --- /dev/null +++ b/text/0000-more-api-documentation-conventions.md @@ -0,0 +1,266 @@ +- Feature Name: More API Documentation Conventions +- Start Date: 2016-03-31 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +[RFC 505] introduced certain conventions around documenting Rust projects. This RFC supersedes +that one, thought it has the same aims: to describe how the Rust project should be documented, +and provide guidance for other Rust projects as well. + +This RFC will contain some similar text as RFC 505, so that we can have one RFC with the full +conventions. + +[RFC 505]: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md + +# Motivation +[motivation]: #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 +[design]: #detailed-design + +This RFC is large. Here’s a table of contents: + +* [Content](#content) + * [Summary sentence](#summary-sentence) + * [English](#english) +* [Form](#form) + * [Use line comments](#use-line-comments) + * [Using Markdown](#using-markdown) +* [Example](#example) + +## Content +[content]: #content + +These conventions relate to the contents of the documentation, the words themselves. + +### Summary sentence +[summary-sentence]: #summary-sentence + +In API documentation, the first line 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. + +The summary line should be written in third person singular present indicative +form. Basically, this means write “Returns” instead of “Return.” + +### English +[english]: #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 +question, but there is often some kind of formal consensus. + +One specific rule that comes up often: when quoting something for emphasis, +use a single quote, and put punctuation outside the quotes, ‘this’. When +quoting something at length, “use double quotes and put the punctuation +inside of the quote.” Most documentation will end up using single quotes, +so if you’re not sure, just stick with them. + +## Form +[form]: #form + +These conventions relate to the formatting of the documentation, how they +appear in source code. + +### Use line comments +[use-line-comments]: #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. When using `mod` blocks, prefer `///` outside of the block: + +```rust +/// This module contains tests +mod test { + // ... +} +``` + +over + +```rust +mod test { + //! This module contains tests + + // ... +} +``` + +### Using Markdown +[using-markdown]: #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 +* Errors +* Safety +* Aborts +* Undefined Behavior + +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. + + ```rust + println!("Hello, world!"); + ``` + + ```ruby + puts "Hello" + ``` + +In API documentation, feel free to rely on the default being ‘rust’: + + /// For example: + /// + /// ``` + /// let x = 5; + /// ``` + +In long-form documentation, always be explicit: + + For example: + + ```rust + let x = 5; + ``` + +This will highlight syntax in places that do not default to ‘rust’, 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 ‘reference style.’ Prefer + +``` +[Rust website] + +[Rust website]: http://www.rust-lang.org +``` + +to + +``` +[Rust website](http://www.rust-lang.org) +``` + +### Examples in API docs +[examples-in-api-docs]: #examples-in-api-docs + +Everything should have examples. Here is an example of how to do examples: + +``` +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// use op; +/// +/// let s = "foo"; +/// let answer = op::compare(s, "bar"); +/// ``` +/// +/// Passing a closure to compare with, rather than a string: +/// +/// ``` +/// use op; +/// +/// let s = "foo"; +/// let answer = op::compare(s, |a| a.chars().is_whitespace().all()); +/// ``` +``` + +For particularly simple APIs, still say “Examples” and “Basic usage:” for +consistency’s sake. + +### Referring to types +[referring-to-types]: #referring-to-types + +When talking about a type, use its full name. In other words, if the type is generic, +say `Option`, not `Option`. An exception to this is lengthy bounds. Write `Cow<'a, B>` +rather than `Cow<'a, B> where B: 'a + ToOwned + ?Sized`. + +Another possibility is to write in lower case using a more generic term. In other words, +‘string’ can refer to a `String` or an `&str`, and ‘an option’ can be ‘an `Option`’. + +### Link all the things +[link-all-the-things]: #link-all-the-things + +A major drawback of Markdown is that it cannot automatically link types in API documentation. +Do this yourself with the reference-style syntax, for ease of reading: + +``` +/// The [`String`] passed in lorum ipsum... +/// +/// [`String`]: ../string/struct.String.html +``` + +## Example +[example]: #example + +Below is a full crate, with documentation following these rules: + +```rust +``` + +## Formatting + +# Drawbacks +[drawbacks]: #drawbacks + +It’s possible that RFC 505 went far enough, and something this detailed is inappropriate. + +# Alternatives +[alternatives]: #alternatives + +We could stick with the more minimal conventions of the previous RFC. + +# Unresolved questions +[unresolved]: #unresolved-questions + +None. From c3d44cd6bf91da54827e7c00206e9f5a51b8230f Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 31 Mar 2016 18:34:45 -0400 Subject: [PATCH 02/14] typo --- text/0000-more-api-documentation-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index 47b52584f43..9bb20a3b523 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -7,7 +7,7 @@ [summary]: #summary [RFC 505] introduced certain conventions around documenting Rust projects. This RFC supersedes -that one, thought it has the same aims: to describe how the Rust project should be documented, +that one, though it has the same aims: to describe how the Rust project should be documented, and provide guidance for other Rust projects as well. This RFC will contain some similar text as RFC 505, so that we can have one RFC with the full From 1330d7b6beafa21e6aab4e49d6ecff1cbbcb4e06 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 4 Apr 2016 17:31:41 -0400 Subject: [PATCH 03/14] example docs --- ...0000-more-api-documentation-conventions.md | 145 +++++++++++++++++- 1 file changed, 144 insertions(+), 1 deletion(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index 9bb20a3b523..f2a81aa8157 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -243,9 +243,152 @@ Do this yourself with the reference-style syntax, for ease of reading: ## Example [example]: #example -Below is a full crate, with documentation following these rules: +Below is a full crate, with documentation following these rules. I am loosely basing +this off of my [ref_slice] crate, because it’s small, but I’m not claiming the code +is good here. It’s about the docs, not the code. + +[ref_slice]: https://crates.io/crates/ref_slice + +In lib.rs: + +```rust +//! Turning references into slices +//! +//! This crate contains several utility functions for taking various kinds +//! of references and producing slices out of them. In this case, only full +//! slices, not ranges for sub-slices. +//! +//! # Layout +//! +//! At the top level, we have functions for working with references, `&T`. +//! There are two submodules for dealing with other types: `option`, for +//! &[`Option`], and `mut`, for `&mut T`. +//! +//! [`Option`]: http://doc.rust-lang.org/std/option/enum.Option.html + +pub mod option; + +/// Converts a reference to `T` into a slice of length 1. +/// +/// This will not copy the data, only create the new slice. +/// +/// # Panics +/// +/// In this case, the code won’t panic, but if it did, the circumstances +/// in which it would would be included here. +/// +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// extern crate ref_slice; +/// use ref_slice::ref_slice; +/// +/// let x = &5; +/// +/// let slice = ref_slice(x); +/// +/// assert_eq!(&[5], slice); +/// ``` +/// +/// A more compelx example. In this case, it’s the same example, because this +/// is a pretty trivial function, but use your imagination. +/// +/// ``` +/// extern crate ref_slice; +/// use ref_slice::ref_slice; +/// +/// let x = &5; +/// +/// let slice = ref_slice(x); +/// +/// assert_eq!(&[5], slice); +/// ``` +pub fn ref_slice(s: &T) -> &[T] { + unimplemented!() +} + +/// Functions that operate on mutable references. +/// +/// This submodule mirrors the parent module, but instead of dealing with `&T`, +/// they’re for `&mut T`. +mod mut { + /// Converts a reference to `&mut T` into a mutable slice of length 1. + /// + /// This will not copy the data, only create the new slice. + /// + /// # Safety + /// + /// In this case, the code doesn’t need to be marked as unsafe, but if it + /// did, the invariants you’re expected to uphold would be documented here. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// extern crate ref_slice; + /// use ref_slice::mut; + /// + /// let x = &mut 5; + /// + /// let slice = mut::ref_slice(x); + /// + /// assert_eq!(&mut [5], slice); + /// ``` + pub fn ref_slice(s: &mut T) -> &mut [T] { + unimplemented!() + } +} +``` + +in `option.rs`: ```rust +//! Functions that operate on references to [`Option`]s. +//! +//! This submodule mirrors the parent module, but instead of dealing with `&T`, +//! they’re for `&`[`Option`]. +//! +//! [`Option`]: http://doc.rust-lang.org/std/option/enum.Option.html + +/// Converts a reference to `Option` into a slice of length 0 or 1. +/// +/// [`Option`]: http://doc.rust-lang.org/std/option/enum.Option.html +/// +/// This will not copy the data, only create the new slice. +/// +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// extern crate ref_slice; +/// use ref_slice::option; +/// +/// let x = &Some(5); +/// +/// let slice = option::ref_slice(x); +/// +/// assert_eq!(&[5], slice); +/// ``` +/// +/// `None` will result in an empty slice: +/// +/// ``` +/// extern crate ref_slice; +/// use ref_slice::option; +/// +/// let x: &Option = &None; +/// +/// let slice = option::ref_slice(x); +/// +/// assert_eq!(&[], slice); +/// ``` +pub fn ref_slice(opt: &Option) -> &[T] { + unimplemented!() +} ``` ## Formatting From 9bf85eb2bf0656ad0c801c7e975896c7df1dcf21 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Tue, 17 May 2016 14:52:50 -0400 Subject: [PATCH 04/14] update a few things Move this to a clear "diff vs unified" style. Fix up graves vs backticks Make note of [long link style][website] for links --- ...0000-more-api-documentation-conventions.md | 70 +++++++++---------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index f2a81aa8157..c474883f886 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -6,12 +6,9 @@ # Summary [summary]: #summary -[RFC 505] introduced certain conventions around documenting Rust projects. This RFC supersedes -that one, though it has the same aims: to describe how the Rust project should be documented, -and provide guidance for other Rust projects as well. - -This RFC will contain some similar text as RFC 505, so that we can have one RFC with the full -conventions. +[RFC 505] introduced certain conventions around documenting Rust projects. This +RFC aguments that one, and a full text of the older one combined with these +modfications is provided below. [RFC 505]: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md @@ -27,15 +24,24 @@ but it tries to motivate and clarify them. # Detailed design [design]: #detailed-design -This RFC is large. Here’s a table of contents: +# Drawbacks +[drawbacks]: #drawbacks + +It’s possible that RFC 505 went far enough, and something this detailed is inappropriate. + +# Alternatives +[alternatives]: #alternatives + +We could stick with the more minimal conventions of the previous RFC. -* [Content](#content) - * [Summary sentence](#summary-sentence) - * [English](#english) -* [Form](#form) - * [Use line comments](#use-line-comments) - * [Using Markdown](#using-markdown) -* [Example](#example) +# Unresolved questions +[unresolved]: #unresolved-questions + +None. + +# Appendix A: Full conventions text + +Below is a combination of RFC 505 + this RFC’s modifications, for convenience. ## Content [content]: #content @@ -50,17 +56,17 @@ 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. The summary line should be written in third person singular present indicative -form. Basically, this means write “Returns” instead of “Return.” +form. Basically, this means write ‘Returns’ instead of ‘Return’. ### English [english]: #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 -question, but there is often some kind of formal consensus. +All documentation for the standard library 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. One specific rule that comes up often: when quoting something for emphasis, use a single quote, and put punctuation outside the quotes, ‘this’. When @@ -130,9 +136,9 @@ Use top level headings # to indicate sections within your comment. Common headin 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 backticks (`) to denote a code fragment within a sentence. -Use triple graves (```) to write longer examples, like this: +Use backticks (```) to write longer examples, like this: This code does something cool. @@ -188,6 +194,14 @@ to [Rust website](http://www.rust-lang.org) ``` +If the text is very long, feel free to use the shortened form: + +``` +This link [is very long and links to the Rust website][website]. + +[website]: http://www.rust-lang.org +``` + ### Examples in API docs [examples-in-api-docs]: #examples-in-api-docs @@ -393,17 +407,3 @@ pub fn ref_slice(opt: &Option) -> &[T] { ## Formatting -# Drawbacks -[drawbacks]: #drawbacks - -It’s possible that RFC 505 went far enough, and something this detailed is inappropriate. - -# Alternatives -[alternatives]: #alternatives - -We could stick with the more minimal conventions of the previous RFC. - -# Unresolved questions -[unresolved]: #unresolved-questions - -None. From e8290fab1366d3e8df6dbc68efdc57c130002211 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 27 May 2016 16:24:57 -0400 Subject: [PATCH 05/14] Address various nits --- text/0000-more-api-documentation-conventions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index c474883f886..707e8c90925 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -7,7 +7,7 @@ [summary]: #summary [RFC 505] introduced certain conventions around documenting Rust projects. This -RFC aguments that one, and a full text of the older one combined with these +RFC augments that one, and a full text of the older one combined with these modfications is provided below. [RFC 505]: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md @@ -148,7 +148,7 @@ Use backticks (```) to write longer examples, like this: x.bar(); ``` -When appropriate, make use of Rustdoc’s modifiers. Annotate triple grave blocks with +When appropriate, make use of Rustdoc’s modifiers. Annotate triple backtick blocks with the appropriate formatting directive. ```rust @@ -236,7 +236,7 @@ consistency’s sake. [referring-to-types]: #referring-to-types When talking about a type, use its full name. In other words, if the type is generic, -say `Option`, not `Option`. An exception to this is lengthy bounds. Write `Cow<'a, B>` +say `Option`, not `Option`. An exception to this is bounds. Write `Cow<'a, B>` rather than `Cow<'a, B> where B: 'a + ToOwned + ?Sized`. Another possibility is to write in lower case using a more generic term. In other words, From 2a378af684c34d577bc2adf688e02a0ac35ef894 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 27 May 2016 16:30:54 -0400 Subject: [PATCH 06/14] Transition to the diff style Now, the RFC proper only includes the new conventions, rather than all of the RFC 505 stuff, in an effort to make what is under discussion more clear. --- ...0000-more-api-documentation-conventions.md | 277 ++++++++++++++++++ 1 file changed, 277 insertions(+) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index 707e8c90925..ac755884a78 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -24,6 +24,283 @@ but it tries to motivate and clarify them. # Detailed design [design]: #detailed-design +## Content +[content]: #content + +These conventions relate to the contents of the documentation, the words themselves. + +### English +[english]: #english + +This section applies to `rustc` and the standard library. + +An additional suggestion over RFC 505: One specific rule that comes up often: +when quoting something for emphasis, use a single quote, and put punctuation +outside the quotes, ‘this’. When quoting something at length, “use double +quotes and put the punctuation inside of the quote.” Most documentation will +end up using single quotes, so if you’re not sure, just stick with them. + +## Form +[form]: #form + +These conventions relate to the formatting of the documentation, how they +appear in source code. + +### Using Markdown +[using-markdown]: #using-markdown + +The updated list of common headings is: + +* Examples +* Panics +* Errors +* Safety +* Aborts +* Undefined Behavior + +RFC 505 suggests that one should always use the `rust` formatting directive: + + ```rust + println!("Hello, world!"); + ``` + + ```ruby + puts "Hello" + ``` + +But, in API documentation, feel free to rely on the default being ‘rust’: + + /// For example: + /// + /// ``` + /// let x = 5; + /// ``` + +Other places do not know how to highlight this anyway, so it's not important to +be explicit. + +RFC 505 suggests that references and citation should be linked ‘reference +style.’ This is still recommended, but prefer to leave off the second `[]`: + +``` +[Rust website] + +[Rust website]: http://www.rust-lang.org +``` + +to + +``` +[Rust website][website] + +[website]: http://www.rust-lang.org +``` + +But, if the text is very long, it is okay to use this form. + +### Examples in API docs +[examples-in-api-docs]: #examples-in-api-docs + +Everything should have examples. Here is an example of how to do examples: + +``` +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// use op; +/// +/// let s = "foo"; +/// let answer = op::compare(s, "bar"); +/// ``` +/// +/// Passing a closure to compare with, rather than a string: +/// +/// ``` +/// use op; +/// +/// let s = "foo"; +/// let answer = op::compare(s, |a| a.chars().is_whitespace().all()); +/// ``` +``` + +For particularly simple APIs, still say “Examples” and “Basic usage:” for +consistency’s sake. + +### Referring to types +[referring-to-types]: #referring-to-types + +When talking about a type, use its full name. In other words, if the type is generic, +say `Option`, not `Option`. An exception to this is bounds. Write `Cow<'a, B>` +rather than `Cow<'a, B> where B: 'a + ToOwned + ?Sized`. + +Another possibility is to write in lower case using a more generic term. In other words, +‘string’ can refer to a `String` or an `&str`, and ‘an option’ can be ‘an `Option`’. + +### Link all the things +[link-all-the-things]: #link-all-the-things + +A major drawback of Markdown is that it cannot automatically link types in API documentation. +Do this yourself with the reference-style syntax, for ease of reading: + +``` +/// The [`String`] passed in lorum ipsum... +/// +/// [`String`]: ../string/struct.String.html +``` + +## Example +[example]: #example + +Below is a full crate, with documentation following these rules. I am loosely basing +this off of my [ref_slice] crate, because it’s small, but I’m not claiming the code +is good here. It’s about the docs, not the code. + +[ref_slice]: https://crates.io/crates/ref_slice + +In lib.rs: + +```rust +//! Turning references into slices +//! +//! This crate contains several utility functions for taking various kinds +//! of references and producing slices out of them. In this case, only full +//! slices, not ranges for sub-slices. +//! +//! # Layout +//! +//! At the top level, we have functions for working with references, `&T`. +//! There are two submodules for dealing with other types: `option`, for +//! &[`Option`], and `mut`, for `&mut T`. +//! +//! [`Option`]: http://doc.rust-lang.org/std/option/enum.Option.html + +pub mod option; + +/// Converts a reference to `T` into a slice of length 1. +/// +/// This will not copy the data, only create the new slice. +/// +/// # Panics +/// +/// In this case, the code won’t panic, but if it did, the circumstances +/// in which it would would be included here. +/// +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// extern crate ref_slice; +/// use ref_slice::ref_slice; +/// +/// let x = &5; +/// +/// let slice = ref_slice(x); +/// +/// assert_eq!(&[5], slice); +/// ``` +/// +/// A more compelx example. In this case, it’s the same example, because this +/// is a pretty trivial function, but use your imagination. +/// +/// ``` +/// extern crate ref_slice; +/// use ref_slice::ref_slice; +/// +/// let x = &5; +/// +/// let slice = ref_slice(x); +/// +/// assert_eq!(&[5], slice); +/// ``` +pub fn ref_slice(s: &T) -> &[T] { + unimplemented!() +} + +/// Functions that operate on mutable references. +/// +/// This submodule mirrors the parent module, but instead of dealing with `&T`, +/// they’re for `&mut T`. +mod mut { + /// Converts a reference to `&mut T` into a mutable slice of length 1. + /// + /// This will not copy the data, only create the new slice. + /// + /// # Safety + /// + /// In this case, the code doesn’t need to be marked as unsafe, but if it + /// did, the invariants you’re expected to uphold would be documented here. + /// + /// # Examples + /// + /// Basic usage: + /// + /// ``` + /// extern crate ref_slice; + /// use ref_slice::mut; + /// + /// let x = &mut 5; + /// + /// let slice = mut::ref_slice(x); + /// + /// assert_eq!(&mut [5], slice); + /// ``` + pub fn ref_slice(s: &mut T) -> &mut [T] { + unimplemented!() + } +} +``` + +in `option.rs`: + +```rust +//! Functions that operate on references to [`Option`]s. +//! +//! This submodule mirrors the parent module, but instead of dealing with `&T`, +//! they’re for `&`[`Option`]. +//! +//! [`Option`]: http://doc.rust-lang.org/std/option/enum.Option.html + +/// Converts a reference to `Option` into a slice of length 0 or 1. +/// +/// [`Option`]: http://doc.rust-lang.org/std/option/enum.Option.html +/// +/// This will not copy the data, only create the new slice. +/// +/// # Examples +/// +/// Basic usage: +/// +/// ``` +/// extern crate ref_slice; +/// use ref_slice::option; +/// +/// let x = &Some(5); +/// +/// let slice = option::ref_slice(x); +/// +/// assert_eq!(&[5], slice); +/// ``` +/// +/// `None` will result in an empty slice: +/// +/// ``` +/// extern crate ref_slice; +/// use ref_slice::option; +/// +/// let x: &Option = &None; +/// +/// let slice = option::ref_slice(x); +/// +/// assert_eq!(&[], slice); +/// ``` +pub fn ref_slice(opt: &Option) -> &[T] { + unimplemented!() +} +``` + # Drawbacks [drawbacks]: #drawbacks From b48a3c4ed1bce8ab82db29b11338e2b19491d934 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 27 May 2016 16:41:33 -0400 Subject: [PATCH 07/14] Add some things @carols10cents brought up --- ...0000-more-api-documentation-conventions.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index ac755884a78..baee94fa430 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -138,6 +138,23 @@ rather than `Cow<'a, B> where B: 'a + ToOwned + ?Sized`. Another possibility is to write in lower case using a more generic term. In other words, ‘string’ can refer to a `String` or an `&str`, and ‘an option’ can be ‘an `Option`’. +### Use parentheses for functions +[use-parentheses-for-functions]: #use-parentheses-for-functions + +When referring to function names, include the `()`s after the name. For example, do this: + +```rust +/// This behavior is similar to the way that `mem::replace()` works. +``` + +Not this: + +```rust +/// This behavior is similar to the way that `mem::replace` works. +``` + +This helps visually differentiate it in the text. + ### Link all the things [link-all-the-things]: #link-all-the-things @@ -150,6 +167,20 @@ Do this yourself with the reference-style syntax, for ease of reading: /// [`String`]: ../string/struct.String.html ``` +### Module-level vs type-level docs +[module-level-vs-type-level-docs]: #module-level-vs-type-level-docs + +There has often been a tension between module-level and type-level +documentation. For example, in today's standard library, the various +`*Cell` docs say, in the pages for each type, to "refer to the module-level +documentation for more details." + +Instead, 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. Module-level +documentation should be broad, and not go into a lot of detail, which is left +to the type's documentation. + ## Example [example]: #example @@ -519,6 +550,23 @@ rather than `Cow<'a, B> where B: 'a + ToOwned + ?Sized`. Another possibility is to write in lower case using a more generic term. In other words, ‘string’ can refer to a `String` or an `&str`, and ‘an option’ can be ‘an `Option`’. +### Use parentheses for functions +[use-parentheses-for-functions]: #use-parentheses-for-functions + +When referring to function names, include the `()`s after the name. For example, do this: + +```rust +/// This behavior is similar to the way that `mem::replace()` works. +``` + +Not this: + +```rust +/// This behavior is similar to the way that `mem::replace` works. +``` + +This helps visually differentiate it in the text. + ### Link all the things [link-all-the-things]: #link-all-the-things @@ -531,6 +579,20 @@ Do this yourself with the reference-style syntax, for ease of reading: /// [`String`]: ../string/struct.String.html ``` +### Module-level vs type-level docs +[module-level-vs-type-level-docs]: #module-level-vs-type-level-docs + +There has often been a tension between module-level and type-level +documentation. For example, in today's standard library, the various +`*Cell` docs say, in the pages for each type, to "refer to the module-level +documentation for more details." + +Instead, 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. Module-level +documentation should be broad, and not go into a lot of detail, which is left +to the type's documentation. + ## Example [example]: #example From f30df3042f8b7109b42a58eb61fccd43cf699d84 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Fri, 27 May 2016 16:44:22 -0400 Subject: [PATCH 08/14] remove excess headers --- ...0000-more-api-documentation-conventions.md | 22 ------------------- 1 file changed, 22 deletions(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index baee94fa430..25a8aaba3e1 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -24,11 +24,6 @@ but it tries to motivate and clarify them. # Detailed design [design]: #detailed-design -## Content -[content]: #content - -These conventions relate to the contents of the documentation, the words themselves. - ### English [english]: #english @@ -40,12 +35,6 @@ outside the quotes, ‘this’. When quoting something at length, “use double quotes and put the punctuation inside of the quote.” Most documentation will end up using single quotes, so if you’re not sure, just stick with them. -## Form -[form]: #form - -These conventions relate to the formatting of the documentation, how they -appear in source code. - ### Using Markdown [using-markdown]: #using-markdown @@ -351,11 +340,6 @@ None. Below is a combination of RFC 505 + this RFC’s modifications, for convenience. -## Content -[content]: #content - -These conventions relate to the contents of the documentation, the words themselves. - ### Summary sentence [summary-sentence]: #summary-sentence @@ -382,12 +366,6 @@ quoting something at length, “use double quotes and put the punctuation inside of the quote.” Most documentation will end up using single quotes, so if you’re not sure, just stick with them. -## Form -[form]: #form - -These conventions relate to the formatting of the documentation, how they -appear in source code. - ### Use line comments [use-line-comments]: #use-line-comments From 4164dfafbcd399b6bc1d96915a15d466fe978875 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 1 Jun 2016 16:07:51 -0400 Subject: [PATCH 09/14] remove random extra formatting header --- text/0000-more-api-documentation-conventions.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index 25a8aaba3e1..d4f525337ca 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -722,5 +722,3 @@ pub fn ref_slice(opt: &Option) -> &[T] { } ``` -## Formatting - From 1ebc429c77b797fa7c7e8fa65dd7e31ec69f60f1 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 20 Jun 2016 13:23:52 -0400 Subject: [PATCH 10/14] more nits --- text/0000-more-api-documentation-conventions.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index d4f525337ca..4d6cf094b8d 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -167,7 +167,7 @@ documentation for more details." Instead, 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. Module-level -documentation should be broad, and not go into a lot of detail, which is left +documentation should be broad and not go into a lot of detail. That is left to the type's documentation. ## Example @@ -410,7 +410,7 @@ mod test { Within doc comments, use Markdown to format your documentation. -Use top level headings # to indicate sections within your comment. Common headings: +Use top level headings (`#`) to indicate sections within your comment. Common headings: * Examples * Panics @@ -419,12 +419,18 @@ Use top level headings # to indicate sections within your comment. Common headin * Aborts * Undefined Behavior +An example: + +```rust +/// # Examples +``` + Even if you only include one example, use the plural form: ‘Examples’ rather than ‘Example’. Future tooling is easier this way. Use backticks (`) to denote a code fragment within a sentence. -Use backticks (```) to write longer examples, like this: +Use triple backticks (```) to write longer examples, like this: This code does something cool. From 66ae85c11db03faa323393eeed44bac724b7db53 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 6 Jul 2016 19:00:40 -0400 Subject: [PATCH 11/14] Remove text relating to https://github.com/rust-lang/rfcs/pull/1574/files#r59055319 --- ...0000-more-api-documentation-conventions.md | 22 ------------------- 1 file changed, 22 deletions(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index 4d6cf094b8d..fe4891e9063 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -95,8 +95,6 @@ Everything should have examples. Here is an example of how to do examples: ``` /// # Examples /// -/// Basic usage: -/// /// ``` /// use op; /// @@ -114,9 +112,6 @@ Everything should have examples. Here is an example of how to do examples: /// ``` ``` -For particularly simple APIs, still say “Examples” and “Basic usage:” for -consistency’s sake. - ### Referring to types [referring-to-types]: #referring-to-types @@ -209,8 +204,6 @@ pub mod option; /// /// # Examples /// -/// Basic usage: -/// /// ``` /// extern crate ref_slice; /// use ref_slice::ref_slice; @@ -255,8 +248,6 @@ mod mut { /// /// # Examples /// - /// Basic usage: - /// /// ``` /// extern crate ref_slice; /// use ref_slice::mut; @@ -291,8 +282,6 @@ in `option.rs`: /// /// # Examples /// -/// Basic usage: -/// /// ``` /// extern crate ref_slice; /// use ref_slice::option; @@ -502,8 +491,6 @@ Everything should have examples. Here is an example of how to do examples: ``` /// # Examples /// -/// Basic usage: -/// /// ``` /// use op; /// @@ -521,9 +508,6 @@ Everything should have examples. Here is an example of how to do examples: /// ``` ``` -For particularly simple APIs, still say “Examples” and “Basic usage:” for -consistency’s sake. - ### Referring to types [referring-to-types]: #referring-to-types @@ -616,8 +600,6 @@ pub mod option; /// /// # Examples /// -/// Basic usage: -/// /// ``` /// extern crate ref_slice; /// use ref_slice::ref_slice; @@ -662,8 +644,6 @@ mod mut { /// /// # Examples /// - /// Basic usage: - /// /// ``` /// extern crate ref_slice; /// use ref_slice::mut; @@ -698,8 +678,6 @@ in `option.rs`: /// /// # Examples /// -/// Basic usage: -/// /// ``` /// extern crate ref_slice; /// use ref_slice::option; From 106fba82e8594aac2a9f8cecd8c55cfb83d38ea8 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 6 Jul 2016 19:01:20 -0400 Subject: [PATCH 12/14] remove text relating to https://github.com/rust-lang/rfcs/pull/1574/files#r67898732 --- ...0000-more-api-documentation-conventions.md | 34 ------------------- 1 file changed, 34 deletions(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index fe4891e9063..4f52591b99c 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -122,23 +122,6 @@ rather than `Cow<'a, B> where B: 'a + ToOwned + ?Sized`. Another possibility is to write in lower case using a more generic term. In other words, ‘string’ can refer to a `String` or an `&str`, and ‘an option’ can be ‘an `Option`’. -### Use parentheses for functions -[use-parentheses-for-functions]: #use-parentheses-for-functions - -When referring to function names, include the `()`s after the name. For example, do this: - -```rust -/// This behavior is similar to the way that `mem::replace()` works. -``` - -Not this: - -```rust -/// This behavior is similar to the way that `mem::replace` works. -``` - -This helps visually differentiate it in the text. - ### Link all the things [link-all-the-things]: #link-all-the-things @@ -518,23 +501,6 @@ rather than `Cow<'a, B> where B: 'a + ToOwned + ?Sized`. Another possibility is to write in lower case using a more generic term. In other words, ‘string’ can refer to a `String` or an `&str`, and ‘an option’ can be ‘an `Option`’. -### Use parentheses for functions -[use-parentheses-for-functions]: #use-parentheses-for-functions - -When referring to function names, include the `()`s after the name. For example, do this: - -```rust -/// This behavior is similar to the way that `mem::replace()` works. -``` - -Not this: - -```rust -/// This behavior is similar to the way that `mem::replace` works. -``` - -This helps visually differentiate it in the text. - ### Link all the things [link-all-the-things]: #link-all-the-things From f9e4f1452ad6053b19db21cf0e7accb262c5f475 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 6 Jul 2016 19:02:06 -0400 Subject: [PATCH 13/14] Remove text relating to https://github.com/rust-lang/rfcs/pull/1574/files#r67826514 Personal note: I don't care at all what ESR thinks, but this was already redundant due to saying American English is the standard. --- text/0000-more-api-documentation-conventions.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/text/0000-more-api-documentation-conventions.md b/text/0000-more-api-documentation-conventions.md index 4f52591b99c..178ac66bdc2 100644 --- a/text/0000-more-api-documentation-conventions.md +++ b/text/0000-more-api-documentation-conventions.md @@ -29,12 +29,6 @@ but it tries to motivate and clarify them. This section applies to `rustc` and the standard library. -An additional suggestion over RFC 505: One specific rule that comes up often: -when quoting something for emphasis, use a single quote, and put punctuation -outside the quotes, ‘this’. When quoting something at length, “use double -quotes and put the punctuation inside of the quote.” Most documentation will -end up using single quotes, so if you’re not sure, just stick with them. - ### Using Markdown [using-markdown]: #using-markdown @@ -332,12 +326,6 @@ 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. -One specific rule that comes up often: when quoting something for emphasis, -use a single quote, and put punctuation outside the quotes, ‘this’. When -quoting something at length, “use double quotes and put the punctuation -inside of the quote.” Most documentation will end up using single quotes, -so if you’re not sure, just stick with them. - ### Use line comments [use-line-comments]: #use-line-comments From fd21c143ff2ac936ea6406c8da6307e195d9de95 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 14 Jul 2016 12:15:43 -0400 Subject: [PATCH 14/14] RFC 1574 is "More API documentation conventions" --- ...-conventions.md => 1574-more-api-documentation-conventions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename text/{0000-more-api-documentation-conventions.md => 1574-more-api-documentation-conventions.md} (100%) diff --git a/text/0000-more-api-documentation-conventions.md b/text/1574-more-api-documentation-conventions.md similarity index 100% rename from text/0000-more-api-documentation-conventions.md rename to text/1574-more-api-documentation-conventions.md