Open MaryaBelanger opened 1 year ago
- Consistent format and information across diagnostic messages
Single line summary
The existing diagnostic messages don't actually have a single line summary, what appears to be a summary is actually the message that's displayed to users in the IDE. We have it there to assure users that they've found the correct documentation.
I'll note, however, that the IDEs also display a correction message (when there is one; not all diagnostics have such a message), which isn't displayed on these pages. The reason it's not displayed is because it's usually a subset of the possible fix options discussed under "Common fixes".
- Standardize process for contributing lint messages
Trial for reviewing in CLs: https://dart-review.googlesource.com/c/sdk/+/278640
That particular CL is related to the non-lint diagnostic messages, though I suppose that the same process can, and should, be used for both kinds of messages.
- Misc. improvements to diagnostic messages
Whether the lint has a quick fix (linter rules have it, diagnostic does not)
That's not accurate. Many lints have quick fixes, but not all of them do, and non-lint diagnostics sometimes have quick fixes, though it's a smaller percentage than for lints.
Wasn't sure which issue to post this in, but I continued a discussion on page length and multiple pages here: https://github.com/dart-lang/site-www/issues/4498#issuecomment-1376065655
Since it sounds like it is expected to mostly only visit diagnostic messages from tooling and IDEs, perhaps it doesn't make sense to have such a long page. We're already having users leave their workflow to visit a site and serving a bunch of information when they likely won't be manually scrolling for other diagnostics doesn't make a lot of sense.
I'm not too concerned about page clutter, especially since we could generate the diagnostic pages as part of the build process from some YAML or JSON structure. Perhaps we could even serve Markdown files too so IDEs could surface the documentation inline (are they capable of that?).
Thanks @bwilkerson, I'll update all these details up top.
That's not accurate. Many lints have quick fixes....
I think what I meant was the non-lint diagnostic message docs don't mention if they have a quick fix or not, but some of the lint docs do (is that accurate? quick ctrl+f "quick fix" on diagnostic-messages shows nothing). I'll update that at the top, thanks for pointing out.
That particular CL is related to the non-lint diagnostic messages...
I also think the same process should eventually be used for both. Like the format of the messages themselves, I think it makes sense to standardize work around the non-lint messages (already very standardized), and then integrate those practices into lint work (as much as possible with the more variant nature of lints)
@parlough I was expecting that conversation to be pretty active so I broke it out, but once a decision is reached I'll update up top with the conclusion. I think as work actually starts for each of these items, they'll probably all warrant their own issues!
I think what I meant was the non-lint diagnostic message docs don't mention if they have a quick fix or not, ...
That's correct.
... but some of the lint docs do ...
All of the lints that have a quick fix associated with them have a badge that indicates that fact. If there's no badge then it's because there's no fix. (The badges are programmatically added so that they can't be out of date.)
Check these issues to be sure you capture everything: https://github.com/dart-lang/site-www/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc+label%3Adiagnostics
There are a lot of small inconsistencies across the diagnostic messages documentation that altogether make the topic's content appear disjointed. For example,
Goal: Restructure the diagnostic message documentation to be more consistent, across messages, pages, and sites.
This issue is for planning/tracking. Most of the points can be addressed asynchronously. Some of the relevant content and the work described lives outside of this repo.
1. Consolidate linter rules with other diagnostic messages
Decision: TBD / Needs input
Issue: https://github.com/dart-lang/site-www/issues/4498
2. Consistent format and information across diagnostic messages
Decision: Rewrite individual linter rules to match diagnostic message format
Issue: https://github.com/dart-lang/linter/issues/3924
The diagnostic messages have a more exact/succinct format to them than the lint messages, so we'll rewrite the lint messages to match that syntax.
This means using the structure of:
Also need to standardize other features of lint messages not included in diagnostic messages:
@atsansone I know you had ideas about restructuring or standardizing the layout of individual messages, if you want to share here
3. Deprecate github.io/linter
Decision: repoint all the tools to dart.dev/tools/linter-rules and BE CAREFUL WITH REDIRECTS
Hosting the lint docs on github.io was decided before the linter rules were added to dart.dev. Now that they're on dart.dev (where they should be, to keep docs in one place), the io page should be deprecated.
A lot of tools point to the io pages though, so the redirects need to be dealt with very carefully.
4. Update how to enable lint instructions
Decision: page hasn't been reviewed in a while, make sure it's up to date
https://dart.dev/guides/language/analysis-options
5. Create guidance page for which lints to use
Decision: Add a page to the static analysis set of pages that provides guidance on which lints to enable for your needs
This will go into detail on the existing common lint sets, and maybe other use cases.
Recreate this page in dart.dev that groups lints by purpose: https://dart-lang.github.io/linter/lints/index.html
6. Standardize process for contributing lint messages
Decision: Document the exact format we decide on for linter rules, and a plan for how they are reviewed
Being addressed here:
Trial for reviewing in CLs: https://dart-review.googlesource.com/c/sdk/+/278640
7. Misc. improvements to diagnostic messages
Decision: pros and cons / benefit vs. cost of each of these needs further evaluation
Adding labels / icons / some other indicators to message docs that indicate things like:
8. (Tangential) Consolidate type promotion error pages
Slightly related to diagnostic messages because some link to Type promotion failures page
Issue: https://github.com/dart-lang/site-www/issues/4393
9. (Tangential) Use the diagnostics glossary as a starting point for a standard site-wide glossary
The Glossary section on the Diagnostic messages page has a wealth of information that is really applicable to the site as a whole. We've discussed taking that content out and putting it on a new page (already created, https://dart.dev/resources/glossary). This would require all the links in the diagnostic and linter docs be updated to point to the same sections on the new page.
Issue: #4622
@bwilkerson @pq