Lint for missing doc-comments on public declarations

[zoechi]

Public declarations should have a doc comment and it would be great if the linter could list missing comments.

[pq]

👍

I've been thinking about this. I chimed in on the dartdoc issue. By public do you mean non-package private or do you mean non-package private and in lib/. (IOW: is the desired definition the same as dartdoc's take on "Public API"?)

[zoechi]

Ideally there would be two rules.
I'm not sure if it is easy to split.

1. Enabled by default: everything exported by files in pkg/lib and reachable from there using public methods/getters (can include files from pkg/lib/src/**)
2. Opt-in: everything not starting with _
   1b) An alternative for the first rule would be to check everything in lib/** not starting with _ and use configuration to exclude what's supposed to be just private implementation.

[pq]

Regarding:

1. Enabled by default: everything exported by files in pkg/lib and reachable from there using public methods/getters (can include files from pkg/lib/src/)
   I see the non-public members that leak into your API as a problem actually. Really there shouldn't be any. I think this should be the thrust of another lint.

All the variations are interesting actually. From my perspective maybe the best to start with would be one that aligns with what dartdoc treats as public API. In other words:

1b) An alternative for the first rule would be to check everything in lib/ not starting with _ and use configuration to exclude what's supposed to be just private implementation.

[zoechi]

I'm not sure I understand 1b)
Usually in lib are dart files without actual code except one or more export src/xxx/xxx/x.dart which are the entry points of the API. If there is a getter which returns ../yyy/y.dart/SomeClass this should be documented.
I have the suspicion that the only reasonable way is to use a configuration to exclude directories if any and otherwise show a hint/warning for everything not starting with _.

[pq]

I think there's some confusion (mine included) on what constitutes package API. My temptation is to start with a lint that is consistent with dartdoc (more on that perspective here: dart-lang/dartdoc#284). Whether we want a more strict variation down the line is an open question.

[pq]

A stab at wording:

DO provide doc comments for all public APIs.

As described in the pub package layout doc, public APIs consist in everything in your package's lib folder, minus implementation files in lib/src, adding elements explicitly exported with an export directive.

For example, given lib/foo.dart:

export 'src/bar.dart' show Bar;
export 'src/baz.dart';

class Foo { }

class _Foo { }

it's API includes:

• Foo (but not _Foo)
• Bar (exported) and
• all public elements in src/baz.dart

All public API members should be documented with /// doc-style comments.

Good:

/// A Foo.
abstract class Foo {
  /// Start foo-ing.
  void start() => _start();

  _start(); 
}

Bad:

class Bar {
  void bar();
}

Advice for writing good doc comments can be found in the Doc Writing Guidelines.

[zoechi]

I think it's a proper defined set and a good starting point. I guess everything else will require a longer discussion. I hope there will be an extended lint which lists all elements not starting with _

[pq]

This one is implemented as public_member_api_docs.