package_api_docs: fix or remove?

[pylaligand]

Here's a simple package:

my_package
    - pubspec.yaml
    - .analysis_options
    - lib
        - class.dart 

with .analysis_options:

linter:
  rules:
    - always_declare_return_types
    - package_api_docs

and class.dart:

class ThisIsATest {
  returnSomething() {
    return 314;
  }
}

If I run the analyzer, I don't get any lint for the lack of documentation:

$ dartanalyzer lib/*.dart
Analyzing [lib/class.dart]...
[lint] Declare method return types. (/work/turquoise/sysui/src/toto/lib/class.dart, line 2, col 3)
1 lint found.

$ dartanalyzer --version
dartanalyzer version 1.15.0

Based on the documentation, I would expect to get a message about ThisIsATest and returnSomething.

[zoechi]

I guess you need

$ dartanalyzer lib/*.dart --lints

[pylaligand]

It seems that --lints is implicit when the options file defines some lint rules. As you can see above, the output of my call to dartanalyzer does contain a lint - I put an additional lint rule precisely to show that lints were being processed.

[kevmoo]

I'm hitting this now. package_api_docs seems to do nothing.

As of 2.0.0-dev.39.0

[devoncarew]

What is package_api_docs supposed to do vs. public_member_api_docs?

[kevmoo]

`public_member_api_docs` is only supposed to warn for APIs that are actually visible to the user – so not things in src (unless exported), nothing in test, example, etc

…

On Fri, Mar 16, 2018 at 10:30 PM Devon Carew ***@***.***> wrote: What is package_api_docs supposed to do vs. public_member_api_docs? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#57310>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABCiuuBsAXHHmJZKqc-icLagtBBTGtiks5tfJ-DgaJpZM4H95dY> .

[srawlins]

Since we've overhauled the command line process for linting (maybe twice), I think this bug is stale. Please re-open if you hit this again.

[leventkantaroglu]

Is there any working example of this rule? I couldn't get any message for this rule.

[pq]

You're right. This lint is not working. Now that we have workspace support it could be fixed. Alternatively we should deprecate it and remove it. Sorry for the confusion!

See also: #58385

[leventkantaroglu]

I think this package_api_docs lint is necessary for packages. Because public_member_api_docs has no option to ignore src folder.

[pq]

Re-opening so we can decide whether to fix or remove.

Thanks for the nudge @leventkantaroglu!