unconditionally complains about short descriptions

[sethladd]

From a user:

One little thing I noticed was that it unconditionally complains about short descriptions, e.g., 'An dart:mirrors.InstanceMirror reflects an instance of a Dart language object' for InstanceMirror in dart:mirrors. But that sentence is very precise and possibly quite appropriate in the concrete context. Maybe the checks could look up some kind of LGTM for the wording and only complain about completely missing entries? ;-)

[srawlins]

Not sure what to do about this one. My opinion is that it should complain about every short description (especially at the class level), and devs shouldn't worry about hitting 100% doc coverage.

[pq]

As a fan of short comments, I tend to agree FWIW.

Where's the logic for this analysis BTW? I was expecting to see it here?

[srawlins]

Sorry, @pq, it should be there, but its in an older bit of code. I'm working on cleaning up the internals as we speak :)

[srawlins]

In general, I would like to make the doc coverage tool configurable, so you can leave out certain complaints. That might be a ways off :)

[pq]

Cool. Thanks for the pointer. Configurability is a tough one. Hopefully you won't need too much of it.

In this case, it's interesting. If I'm reading this right, you're minimum is 2 lines? Curious how well the SDK fares against this standard. I'm thinking getters in particular would commonly have just one line.

[srawlins]

That should just be for "top-level" comments (for classes and libraries, not methods).

[pq]

Aha. That's better! :)

In the long run, I should get a handle on the exact rules so we can codify the appropriate ones in the linter as well. Anyway, we can connect on that down the road.

Thanks!