Standardize _details

[MaryaBelanger]

I noticed a few minor aspects of lints' _details are pretty non-standard. This seems counter-productive for users looking for a quick solution, if that information is formatted differently every time it pops up.

1. Different lints anchor to Effective Dart in different ways:
   • From the style guide...
   • Per Effective Dart...
   • From Effective Dart...
2. Some have a sentence summary before linking to Effective Dart, others link to Effective Dart first.
3. Some provide a lot of info in the details.

I'd be happy to do the actual standardization across all the lints if the team wants to agree on standards.

My take:

1. I don't feel strongly about any of them, just that we pick one phrase and stick to it (i.e. always say "From Effective Dart...").
2. Don't feel strongly either way. I kind of like info first, followed by a link, e.g.:

   Use var, not final, when declaring local variables. From Effective Dart.

3. Lint details should be as succinct, actionable, and brief as possible, and then link to a corresponding Effective Dart section for more details. Any lint with an exact copy of an effective dart section in its details should be rewritten to summarize that info instead.

---

link to dart-lang/site-www#4393

[bwilkerson]

Do we want to do this as part of rewriting the documentation to conform to (and be incorporated in) the other diagnostic messages documentation, or do we want to do this in place of merging the documentation together?

[MaryaBelanger]

The former, this doesn't need to be done separately.
In that light, another question is what conforming to the diagnostic messages looks like.

Effective Dart points to linter rules and vice versa. But it seems like there's no linking/connection between Effective Dart and diagnostic messages in either direction. (I could be mistaken, could you point me to the source of a diagnostic message, like the equivalent of the individual lint sources I linked to in my original description? I'm just looking at the rendered docs and don't see any links.)

So, do we want linter docs to conform to diagnostics in the sense that they don't have a connection to Effective Dart at all?

• If yes, then we don't need to consider any of the original points I brought up, there just won't be any mention of Effective Dart anymore.
• But if it's still important for linter rules to reference Effective Dart, how that reference is written into the diagnostic message "Description" section is still something that should be standardized. It'll make it easier to start that work soon too.

[bwilkerson]

Kind of a long winded answer, but hopefully there's some useful background info somewhere in it.

There are three kinds of diagnostics produced by the analyzer:

• errors, which are issues defined by the language spec that prevent code from being compiled and run,
• warnings, which are issues that are known to indicate bugs in code but that (for the most part) aren't in the language spec, and
• lints, which are additional checks, whether related to bugs or stylistic preferences, that users can opt-in to.

Effective Dart is a set of primarily stylistic advice that reflects the common use of the language in the community.

Some of the advice in Effective Dart can be checked statically, and for those cases we try to have a lint that can do the checking, but not all of the advice can be checked statically, so there are no lints for those pieces. Similarly, not all of the lints are related to advice in Effective Dart. So, there is an overlap between the two, but not a 1-to-1 correspondence, and neither is a subset of the other.

But you're correct that there's no overlap between Effective Dart and the non-lint diagnostics, simply because of the way we group diagnostics into the kinds above.

Because we started writing lint documentation before any other diagnostics had been documented, we just chose a convenient place for the docs to live. Later, when we started documenting the non-lint diagnostics (an ongoing process), that location wasn't deemed to be appropriate, so a new location was chosen. The desire is to move all of the documentation for all of the diagnostics into the same location, and part of that work would likely require that the lint documentation follow a format similar to the other diagnostic documentation. Though exactly what that means is open to discussion (a discussion I hope we can have fairly soon).

I think we want to make it clear in the diagnostic documentation whether the diagnostic is an error, warning, or lint. I think the documentation for lints that correspond to advice in Effective Dart should have a link (and vice versa).

I think that when we restructure the lint documentation we should consider having some sections that don't appear in non-lint docs. I think it's useful to have both a "Description" section that describes what the lint does and a "Motivation" (or some such) section that describes why this is useful to a user, which in some cases would just be a pointer back to Effective Dart. But I'd like to morph all of the "GOOD" and "BAD" examples into the "Examples" and "Common Fixes" style because I think it's more helpful to describe what the change is than to just show the changed code. There are lots of details that we need to work through.

And to answer your question: the documentation for the non-lint diagnostic is kept in a YAML file (https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/messages.yaml#L163), which is used to generate, among other files, a markdown file (https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/tool/diagnostics/diagnostics.md) that is then uploaded to the web site.