From 5ed4edd012be49e2ec8d5662212564b7e53a68e6 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 1 Jun 2022 16:00:04 +0200 Subject: [PATCH 1/2] Updates on "how to write documentation" --- src/documentation/how-to-write-documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/documentation/how-to-write-documentation.md b/src/documentation/how-to-write-documentation.md index 2c88147..9679a9b 100644 --- a/src/documentation/how-to-write-documentation.md +++ b/src/documentation/how-to-write-documentation.md @@ -39,9 +39,9 @@ Intra-doc links (you can see the full explanations for the feature [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html)) should be used as much as possible whenever a type is mentioned. -Little note: when you are documenting an item, no need to link to it. So if you -write documentation for `String::push_str` method, no need to link to the method -`push_str` or to the `String` type. +Little note: when you are documenting an item, there is no need to link to it. +So, if you write documentation for the `String::push_str` method, there is +no need to link to the `push_str` method or the `String` type. If you have cases like `Vec`, you need to use intra-doc links on both `Vec` and `String` as well. It would look like this: From ac6554bcd800d14b46c6475c3b9041487f2e1f95 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 2 Jun 2022 16:59:53 +0200 Subject: [PATCH 2/2] Remove controversial parts of "how to write documentation" --- .../how-to-write-documentation.md | 33 ++----------------- 1 file changed, 3 insertions(+), 30 deletions(-) diff --git a/src/documentation/how-to-write-documentation.md b/src/documentation/how-to-write-documentation.md index 9679a9b..eac10ab 100644 --- a/src/documentation/how-to-write-documentation.md +++ b/src/documentation/how-to-write-documentation.md @@ -4,24 +4,6 @@ This document explains how to write documentation for the std/core public APIs. Let's start with some general information: -### Contractions - -It is common in English to have contractions such as "don't" or "can't". Do not -use these in documentation. Always write their "full form": - - * "do not" instead of "don't" - * "cannot" instead of "can't" - * "it would" instead of "it'd" - * "it will" instead of "it'll" - * "it is"/"it has" instead of "it's" - * "you are" instead of "you're" - * "they are" instead of "they're" - * etc - -The only exception to this rule is "let's" as it is specific/known/common enough. - -The reason is simply to make the reading simpler for as many people as possible. - ### When to use inline code blocks Whenever you are talking about a type or anything code related, it should be in a @@ -43,16 +25,6 @@ Little note: when you are documenting an item, there is no need to link to it. So, if you write documentation for the `String::push_str` method, there is no need to link to the `push_str` method or the `String` type. -If you have cases like `Vec`, you need to use intra-doc links on both -`Vec` and `String` as well. It would look like this: - -```text -This is a [`Vec`]`<`[`String`]`>`. -``` - -Extra explanations: since both `Vec` and `String` are in codeblocks, `<` and `>` -should as well, otherwise it would render badly. - ### Code blocks With rustdoc, code blocks are tested (because they are treated as Rust code @@ -130,14 +102,15 @@ mentioned! This explanation needs to be prepended by a `Panics` title: ### Examples As for the examples, they have to show the usage of the function/method. Just -like the `panic` section, they need to be prepended by a `Examples` title. +like the `panic` section, they need to be prepended by a `Example` title (plural +if there is more than one). It is better if you use `assert*!` macros at the end to ensure that the example is working as expected. It also allows the readers to understand more easily what the function is doing (or returning). ````text -# Examples +# Example ``` let s = MyType::new("hello ");