Hints like unused_local_variable missing from linter docs

[DetachHead]

Describe the issue
https://dart-lang.github.io/linter/lints/index.html
https://dart-lang.github.io/linter/lints/unused_local_variable.html - 404 error

[srawlins]

unused_local_variable is not a Lint defined in the linter, but a Hint (more like a Warning) defined in the SDK. See https://dart.dev/tools/diagnostic-messages#unused_local_variable.

[srawlins]

CC @bwilkerson. I think you discussed a common diagnostics location, on another issue.

[bwilkerson]

Yes, we've discussed moving the lint documentation to the same location as the other diagnostics. Not sure whether it's a good idea (especially given the evidence that some users are very familiar with the current location), but even if it would be a good idea, it's probably not a high priority.

[DetachHead]

Maybe if there is was some indication in the dart analyze output that says whether a rule is a lint or a diagnostic it would be less confusing

[bwilkerson]

Confusion abounds. :-(

A diagnostic is an indication of a problem in the code. A lint is a diagnostic that is disabled by default.

The fact that lints are implemented in the linter package while every other kind of diagnostic is implemented in the analyzer package is an implementation detail that shouldn't be visible to users. Unfortunately, because of where we've put the documentation for lints, it becomes somewhat visible.

Maybe if there is was some indication in the dart analyze output that says whether a rule is a lint ...

I'm not sure whether that would be a good thing or not. Ideally the user shouldn't need to know which are from lints. Of course, the current state is not ideal, so ... :-/

But I will point out that dart analyze includes, as part of its output, the URL of the documentation for every diagnostic that has documentation. You should be able to use that URL to navigate to the documentation without needing to think about whether the diagnostic was generated by a lint or not.

[DetachHead]

Yes, we've discussed moving the lint documentation to the same location as the other diagnostics. Not sure whether it's a good idea (especially given the evidence that some users are very familiar with the current location)

The fact that lints are implemented in the linter package while every other kind of diagnostic is implemented in the analyzer package is an implementation detail that shouldn't be visible to users. Unfortunately, because of where we've put the documentation for lints, it becomes somewhat visible.

imo if this is an implementation detail that users aren't meant to see, i think it would be better if the documentation was moved even if there are some users used to the current state

But I will point out that dart analyze includes, as part of its output, the URL of the documentation for every diagnostic that has documentation. You should be able to use that URL to navigate to the documentation without needing to think about whether the diagnostic was generated by a lint or not.

is there an argument i need to pass to enable for this? i'm not seeing any urls in the output:

>dart analyze
Analyzing project...

  error • lib\screens\foo.dart:13:11 • The value of the local variable 'foo' isn't used. Try removing the variable or using it. • unused_local_variable
  error • test\widget_test.dart:10:8 • Target of URI doesn't exist: 'package:project/main.dart'. Try creating the file referenced by the URI, or Try using a URI for a file that does exist. • uri_does_not_exist
  error • test\widget_test.dart:15:35 • The name 'HomeRoute' isn't a class. Try correcting the name to match an existing class. • creation_with_non_type
   info • lib\screens\foo.dart:5:7 • This class (or a class that this class inherits from) is marked as '@immutable', but one or more of its instance fields aren't final: ReportRoute.report, ReportRoute.onSave • must_be_immutable

4 issues found.

i know there are documentation links when you hover over the warnings in the IDE, but i think they should also be present in the dart analyze output like you said, especially if it's not obvious where to look for said docs

[bwilkerson]

I thought it was the default behavior, but it appears that you need to include the --verbose flag in order to get that information. FWIW, I consider that to be a bug.

dart analyze

   info • lib/test.dart:2:7 • The value of the local variable 'x' isn't used. Try removing the variable or using it. •
          unused_local_variable

dart analyze --verbose

   info • lib/test.dart:2:7 • The value of the local variable 'x' isn't used. Try removing the variable or using it. •
          https://dart.dev/diagnostics/unused_local_variable

[srawlins]

CC @parlough and @pq was this resolved recently?

[parlough]

I think the core issue raised here is that linter rules are treated differently by the analyzer from other diagnostics. To solve this, we're currently working on adding consistent diagnostic documentation for linter rules to the same location and in the same format as other diagnostics.

We're tracking that work in dart-lang/site-www#4498 among other issues, so perhaps this issue can be closed in favor of those.