Skip to content

Commit 0cb9115

Browse files
authored
Merge pull request #38 from GuillaumeGomez/how-to-write-docs
Updates on "how to write documentation"
2 parents 1154bff + ac6554b commit 0cb9115

File tree

1 file changed

+6
-33
lines changed

1 file changed

+6
-33
lines changed

src/documentation/how-to-write-documentation.md

+6-33
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,6 @@ This document explains how to write documentation for the std/core public APIs.
44

55
Let's start with some general information:
66

7-
### Contractions
8-
9-
It is common in English to have contractions such as "don't" or "can't". Do not
10-
use these in documentation. Always write their "full form":
11-
12-
* "do not" instead of "don't"
13-
* "cannot" instead of "can't"
14-
* "it would" instead of "it'd"
15-
* "it will" instead of "it'll"
16-
* "it is"/"it has" instead of "it's"
17-
* "you are" instead of "you're"
18-
* "they are" instead of "they're"
19-
* etc
20-
21-
The only exception to this rule is "let's" as it is specific/known/common enough.
22-
23-
The reason is simply to make the reading simpler for as many people as possible.
24-
257
### When to use inline code blocks
268

279
Whenever you are talking about a type or anything code related, it should be in a
@@ -39,19 +21,9 @@ Intra-doc links (you can see the full explanations for the feature
3921
[here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html))
4022
should be used as much as possible whenever a type is mentioned.
4123

42-
Little note: when you are documenting an item, no need to link to it. So if you
43-
write documentation for `String::push_str` method, no need to link to the method
44-
`push_str` or to the `String` type.
45-
46-
If you have cases like `Vec<String>`, you need to use intra-doc links on both
47-
`Vec` and `String` as well. It would look like this:
48-
49-
```text
50-
This is a [`Vec`]`<`[`String`]`>`.
51-
```
52-
53-
Extra explanations: since both `Vec` and `String` are in codeblocks, `<` and `>`
54-
should as well, otherwise it would render badly.
24+
Little note: when you are documenting an item, there is no need to link to it.
25+
So, if you write documentation for the `String::push_str` method, there is
26+
no need to link to the `push_str` method or the `String` type.
5527

5628
### Code blocks
5729

@@ -130,14 +102,15 @@ mentioned! This explanation needs to be prepended by a `Panics` title:
130102
### Examples
131103

132104
As for the examples, they have to show the usage of the function/method. Just
133-
like the `panic` section, they need to be prepended by a `Examples` title.
105+
like the `panic` section, they need to be prepended by a `Example` title (plural
106+
if there is more than one).
134107

135108
It is better if you use `assert*!` macros at the end to ensure that the example
136109
is working as expected. It also allows the readers to understand more easily
137110
what the function is doing (or returning).
138111

139112
````text
140-
# Examples
113+
# Example
141114
142115
```
143116
let s = MyType::new("hello ");

0 commit comments

Comments
 (0)