Skip to content

Commit 010e479

Browse files
HavvyHavvy
authored
Merge guidelines from RFC 1567 into UX Guidelines.
This is a partial fix for issue #34808. Most of the wording was copied verbatim from the RFC. Main difference is that I moved the actual template to the top of the section. It also makes the error explanations the longest section in the guidelines doc for now.
1 parent 34f35ed commit 010e479

File tree

1 file changed

+122
-0
lines changed

1 file changed

+122
-0
lines changed

Diff for: ‎src/doc/rustc-ux-guidelines.md

+122
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,10 @@ Error explanations are long form descriptions of error messages provided with
5656
the compiler. They are accessible via the `--explain` flag. Each explanation
5757
comes with an example of how to trigger it and advice on how to fix it.
5858

59+
Long error codes explanations are a very important part of Rust. Having an
60+
explanation of what failed helps to understand the error and is appreciated by
61+
Rust developers of all skill levels.
62+
5963
* All of them are accessible [online](http://doc.rust-lang.org/error-index.html),
6064
which are auto-generated from rustc source code in different places:
6165
[librustc](https://github.com/rust-lang/rust/blob/master/src/librustc/diagnostics.rs),
@@ -74,6 +78,124 @@ code with backticks.
7478
* When talking about the compiler, call it `the compiler`, not `Rust` or
7579
`rustc`.
7680

81+
Note: The following sections are mostly a repaste of [RFC 1567](https://github.com/rust-lang/rfcs/blob/master/text/1567-long-error-codes-explanation-normalization.md).
82+
83+
### Template
84+
85+
Long error descriptions should match the following template. The next few
86+
sections of this document describe what each section is about.
87+
88+
```rust
89+
E000: r##"
90+
[Error description]
91+
92+
Example of erroneous code:
93+
94+
\```compile_fail
95+
[Minimal example]
96+
\```
97+
98+
[Error explanation]
99+
100+
\```
101+
[How to fix the problem]
102+
\```
103+
104+
[Optional Additional information]
105+
```
106+
107+
### Error description
108+
109+
Provide a more detailed error message. For example:
110+
111+
```rust
112+
extern crate a;
113+
extern crate b as a;
114+
```
115+
116+
We get the `E0259` error code which says "an extern crate named `a` has already been imported in this module" and the error explanation says: "The name chosen for an external crate conflicts with another external crate that has been imported into the current module.".
117+
118+
### Minimal example
119+
120+
Provide an erroneous code example which directly follows `Error description`. The erroneous example will be helpful for the `How to fix the problem`. Making it as simple as possible is really important in order to help readers to understand what the error is about. A comment should be added with the error on the same line where the errors occur. Example:
121+
122+
```rust
123+
type X = u32<i32>; // error: type parameters are not allowed on this type
124+
```
125+
126+
If the error comments is too long to fit 80 columns, split it up like this, so the next line start at the same column of the previous line:
127+
128+
```rust
129+
type X = u32<'static>; // error: lifetime parameters are not allowed on
130+
// this type
131+
```
132+
133+
And if the sample code is too long to write an effective comment, place your comment on the line before the sample code:
134+
135+
```rust
136+
// error: lifetime parameters are not allowed on this type
137+
fn super_long_function_name_and_thats_problematic() {}
138+
```
139+
140+
Of course, it the comment is too long, the split rules still applies.
141+
142+
### Error explanation
143+
144+
Provide a full explanation about "__why__ you get the error" and some leads on __how__ to fix it. If needed, use additional code snippets to improve your explanations.
145+
146+
### How to fix the problem
147+
148+
This part will show how to fix the error that we saw previously in the `Minimal example`, with comments explaining how it was fixed.
149+
150+
### Additional information
151+
152+
Some details which might be useful for the users, let's take back `E0109` example. At the end, the supplementary explanation is the following: "Note that type parameters for enum-variant constructors go after the variant, not after the enum (`Option::None::<u32>`, not `Option::<u32>::None`).". It provides more information, not directly linked to the error, but it might help user to avoid doing another error.
153+
154+
### Full Example
155+
156+
Now let's take a full example:
157+
158+
> E0409: r##"
159+
> An "or" pattern was used where the variable bindings are not consistently bound
160+
> across patterns.
161+
>
162+
> Example of erroneous code:
163+
>
164+
> ```compile_fail
165+
> let x = (0, 2);
166+
> match x {
167+
> (0, ref y) | (y, 0) => { /* use y */} // error: variable `y` is bound with
168+
> // different mode in pattern #2
169+
> // than in pattern #1
170+
> _ => ()
171+
> }
172+
> ```
173+
>
174+
> Here, `y` is bound by-value in one case and by-reference in the other.
175+
>
176+
> To fix this error, just use the same mode in both cases.
177+
> Generally using `ref` or `ref mut` where not already used will fix this:
178+
>
179+
> ```ignore
180+
> let x = (0, 2);
181+
> match x {
182+
> (0, ref y) | (ref y, 0) => { /* use y */}
183+
> _ => ()
184+
> }
185+
> ```
186+
>
187+
> Alternatively, split the pattern:
188+
>
189+
> ```
190+
> let x = (0, 2);
191+
> match x {
192+
> (y, 0) => { /* use y */ }
193+
> (0, ref y) => { /* use y */}
194+
> _ => ()
195+
> }
196+
> ```
197+
> "##,
198+
77199
## Compiler Flags
78200

79201
* Flags should be orthogonal to each other. For example, if we'd have a

0 commit comments

Comments
 (0)