RFC: (Re)standardise error code documentation#3370
RFC: (Re)standardise error code documentation#3370Ezrashaw wants to merge 2 commits intorust-lang:masterfrom
Conversation
|
|
||
| This RFC makes three changes to error docs in order to fulfill this RFC's (and [RFC 1567]'s) goals: | ||
|
|
||
| - Firstly, that the style of error docs is not defined by RFC but by a "style spec" located in the `rust-lang/rust` repository. This style spec can be updated from time-to-time in order to ensure consistent formatting across error docs. Any change to the style spec must be with the consensus of the dev-tools team. It is recommended that the style spec is initially extracted from [RFC 1567]. |
There was a problem hiding this comment.
Might be worth giving the path to the style spec.
There was a problem hiding this comment.
Hmm, should we put it in compiler/rustc_error_codes/STYLE_SPEC.md?
There was a problem hiding this comment.
Just realized that it doesn't exist yet. Question for other reviewers: should this style spec be written before this RFC is merged or after is fine?
There was a problem hiding this comment.
Hmm, should we put it in
compiler/rustc_error_codes/STYLE_SPEC.md?
That seems like a good idea.
| [unresolved-questions]: #unresolved-questions | ||
|
|
||
| - Is the current `mdBook` format used to present error docs still sufficient? Its index page is very unappealing and makes it hard to quickly jump to an error. Furthermore, it does not interface well with the new idea of error doc labels and cannot quickly show labels applied to an error. | ||
| - Should changes to the style spec require more or less than "dev-tools team consensus"? |
There was a problem hiding this comment.
It's actually two questions:
- Should changes to the style spec require more or less a "team" consensus?
- Which team should be in charge of error codes?
There was a problem hiding this comment.
-
Hmm, perhaps a good standard would be "changes that would in turn require modifications to the docs" (so then spelling changes, etc to the spec would be fine)?
-
As for the team, I obviously agree that dev-tools is wrong. I also am somewhat opposed to wg-diagnostics having anything to do with it, they seem focused on changes to error messages themselves, no docs. Worst case, the docs team is reformed or something.
There was a problem hiding this comment.
the docs team is reformed or something.
It's complicated. ^^'
| # Rationale and alternatives | ||
| [rationale-and-alternatives]: #rationale-and-alternatives | ||
|
|
||
| Some changes must be made, otherwise PR authors coming up with their own formatting for error docs will continue to increase. *This is already happening* and only makes error docs harder to understand. |
There was a problem hiding this comment.
The problem here is that we need a better way to "split" the error code explanation. For example have the following parts well defined:
- Short explanation
- Erroneous code example
- Long explanation of what's going on
- (optional) How to fix it
- (optional) Fixed code example
If we have a format that forces to follow this, it'd be much simpler.
There was a problem hiding this comment.
Yes, obviously this gets more complex when you bring in code examples that involve multiple crates, feature gates, etc. Also things like defining where the error is with comments (like UI tests) is a bit nonstandard.
Hopefully one day I can have some fun with a finite-state machine parser in tidy :)
There was a problem hiding this comment.
Well, since you're adding labels, we can also add labels for parts. That would make it much simpler.
There was a problem hiding this comment.
I don't quite get it? Labels are optional attributes for certain error codes (like real Rust attributes) whereas that sounds more mandatory (like trait impls) with more internal compiler maintenance, not just a style spec.
There was a problem hiding this comment.
The primary goal of this RFC is to enforce a style on the error code explanations/ You suggested to add labels to know the "kind" of the error code. We can go even further and even force to have specific sections that can be checked with tidy to prevent having multiple styles (or at least limit it even more).
There was a problem hiding this comment.
Yeah, as mentioned in the RFC, tidy linting is a important part of this. I'm not sure about expanding labels like this. Not opposed, just need to think about it for a bit.
|
@GuillaumeGomez I've applied one of your suggestions, I think the rest are more unresolved questions. I also have a initial style spec, pulled from RFC 1567, ready to PR on the main repo if you want. |
|
RFC looks good to me, thanks for writing it! I'm not sure what happens for the RFC approval and merge now though. |
Some discussion also occurred on Zulip here.
The devtools teams (as referenced in the RFC) is not the correct team to handle changes to the proposed "style spec". It is unclear which team would maintain this, that should be decided before this is accepted (everything else I'm happy with).
cc @GuillaumeGomez @ehuss @rylev @calebcartwright (from Zulip)
Rendered