Skip to content

RFC: (Re)standardise error code documentation #3370

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Ezrashaw wants to merge 2 commits into
base: master
Choose a base branch
from
Open

RFC: (Re)standardise error code documentation #3370

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
59fe1c1
add standardize-error-docs RFC
Ezrashaw Jan 10, 2023
5176006
add examples of where labels could be shown
Ezrashaw Jan 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions text/0000-standardize-error-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
- Feature Name: standardize_error_docs
- Start Date: 2023-01-10
- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000)

# Summary
[summary]: #summary

(Re)-standardize long-form error code explanations (referred to in this RFC as "error docs") with a more flexible system that also takes into account new errors which do not fit into the format as defined by [RFC 1567]. This RFC replaces [RFC 1567] as the primary specification for error docs. This RFC ultimately wishes to make error docs more accessible and easy to read for both new and proficient Rust users.

# Motivation
[motivation]: #motivation

[RFC 1567] provided a standard that fulfilled its aim of ensuring *readable* and *helpful* error docs. However many changes have occurred to error docs since the RFC, such as [error docs being moved to their own files](https://github.com/rust-lang/rust/pull/66314), [error docs' examples use multiple crates](https://github.com/rust-lang/rust/pull/106028) and [documentation of internal error codes](https://github.com/rust-lang/rust/pull/106614). These changes, among others, now make [RFC 1567] out of date and re-creates the very problem [RFC 1567] solved: nonstandardized error docs.

# Guide-level explanation
[guide-level-explanation]: #guide-level-explanation

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].
Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be worth giving the path to the style spec.

Copy link
Author

@Ezrashaw Ezrashaw Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, should we put it in compiler/rustc_error_codes/STYLE_SPEC.md?

Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, should we put it in compiler/rustc_error_codes/STYLE_SPEC.md?

That seems like a good idea.

- Secondly, that the idea of "labels" is introduced to error docs. These would specify certain attributes about an error code that are important for users to know. Error codes can be marked with labels easily and are verified at compile-time (this would probably happen in the `register_diagnostics` macro). These labels would be added as markdown headers at doc-time and would replace the current typo-prone system of copying long lines around. Labels will be displayed in visible places in order to quickly show the user important attributes of certain error codes. For example, they could be shown in the text generated for the `--explain` flag and shown as colored badges on the error index site. Labels are defined in the style spec. Three label-candidates are exampled here:
- `removed`: An error code has been removed, and therefore the labeled docs docs exist for backwards-compatibility purposes only. The docs may also contain a note explaining *where* the error code was moved to, if at all. (The style spec can specify this more fully)
- `internal`: An error code is internal to the compiler/standard library. This means that it can only occur when using a perma-unstable feature gate which is explicitly marked as only intended for use internally.
- `feature_gated`: An error code can only be emitted when using an unstable feature. This error is subject to change or removal, all the normal feature gate non-guarantees apply.
- Thirdly, that error docs (including the new labels feature) are aggressively linted according to the style spec. This helps keep the error docs consistently styled.

# Drawbacks
[drawbacks]: #drawbacks

It requires a lot of effort:
- The error docs check in `tidy` will have to be kept up to date with the style spec.
- Error docs will have to be kept up to date with the style spec.

# 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.
Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem here is that we need a better way to "split" the error code explanation. For example have the following parts well defined:

  1. Short explanation
  2. Erroneous code example
  3. Long explanation of what's going on
  4. (optional) How to fix it
  5. (optional) Fixed code example

If we have a format that forces to follow this, it'd be much simpler.

Copy link
Author

@Ezrashaw Ezrashaw Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :)

Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, since you're adding labels, we can also add labels for parts. That would make it much simpler.

Copy link
Author

@Ezrashaw Ezrashaw Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Author

@Ezrashaw Ezrashaw Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


# Prior art
[prior-art]: #prior-art

[RFC 1567] is prior art, its significance to this RFC was mentioned in the [motivation] section.

# Unresolved questions
[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"?
Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's actually two questions:

  1. Should changes to the style spec require more or less a "team" consensus?
  2. Which team should be in charge of error codes?

Copy link
Author

@Ezrashaw Ezrashaw Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. 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)?

  2. 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.

Copy link
Member

@GuillaumeGomez GuillaumeGomez Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the docs team is reformed or something.

It's complicated. ^^'


# Future possibilities
[future-possibilities]: #future-possibilities

Perhaps every couple years this RFC (and maybe other related things) is reviewed and a decision is made around whether changes are needed? I'm not sure about formalizing this process though.

[RFC 1567]: https://rust-lang.github.io/rfcs/1567-long-error-codes-explanation-normalization.html