@@ -4,24 +4,6 @@ This document explains how to write documentation for the std/core public APIs.
4
4
5
5
Let's start with some general information:
6
6
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
-
25
7
### When to use inline code blocks
26
8
27
9
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
39
21
[ here] ( https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html ) )
40
22
should be used as much as possible whenever a type is mentioned.
41
23
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.
55
27
56
28
### Code blocks
57
29
@@ -130,14 +102,15 @@ mentioned! This explanation needs to be prepended by a `Panics` title:
130
102
### Examples
131
103
132
104
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).
134
107
135
108
It is better if you use ` assert*! ` macros at the end to ensure that the example
136
109
is working as expected. It also allows the readers to understand more easily
137
110
what the function is doing (or returning).
138
111
139
112
```` text
140
- # Examples
113
+ # Example
141
114
142
115
```
143
116
let s = MyType::new("hello ");
0 commit comments