Q: Why is doc comments score and anlysis broken on pub?

[rydmike]

I'm curious, what is it that causes doc scoring to break completely by pub pana anlysis?

It is the same with latest stable 4.5.1 and new 5.0.0 beta3 release:

This is not good and should not be like this. I have not seen this issue with other packages before.

[rodydavis]

Yeah not really sure. I added a lot of code example and inline documentation to a lot of the api now.

[rydmike]

I don't think that matters, it is in fact a good thing and should show up as improved documentation %. However, something in the setup is preventing it from working correctly, so there is no report at all on the API documentation coverage. The analyzer is apparently running into something that it cannot handle.

I will take a closer peek at it too and see if I can spot something that is off, there are some leads in the error message.

[rodydavis]

Fixed on 5.0.0-beta.5

[rydmike]

Nice Rody! That was fast, I did not even have time to take look yet 😀

What was it that triggered the error? I looked at the commit, but there were so many changes, so it was hard to figure out what might have been the cause of pub not liking it before. Just curious, so I know what to avoid myself, because I have not seen this error message from pub before.

I saw you added the lint rule public_member_api_docs. I was going to suggest it as well. It is a tedious rule, not really recommended for an app, but perfect and very helpful for a public and popular package.

Now API doc % is at:

10/10 points: 20% or more of the public API has dartdoc comments
398 out of 414 API elements (96.1 %) have documentation comments.
Some symbols that are missing documentation: signals, signals.DISPOSED, signals.HAS_ERROR, signals.NOTIFIED, signals.OUTDATED.

So only 16 comments remaining to have 100% API Doc comments, as all packages should have! 😉💙
This is actually super good public API doc coverage already, very few packages are at this level.

Still, once you get to 100%, keeping it there is actually quite easy going forward.

Sadly the lint rule public_member_api_docs does not seem to detect all places where doc comments are missing, at least it did not use to. So finding the last missing ones may be tricky, as you might not be seeing any lint warnings for the last missing API doc comments, but maybe for some of them.

It can also be an issues of pub reporting the number wrong. For the longest time pub used to report that I was missing 4 doc comments somewhere in one of my packages. No info on where or what, and I could not find any place where they might be missing. Recently that analysis result changed and it now says it is 100%, and I did not change anything. Clearly the dart team fixed something in the analysis of missing API doc comments. There may still be similar issues in it as well, if so you won't ever be able to "catch" them all. For now it is at least even listing a few examples.

Anyway, thanks Rody for your the effort with improving doc comments, both content and their coverage. Love it! 💙

[rodydavis]

Thanks! There are some private variables that are not exported that are public in the package but not public to the export that I think is tripping it up.

The analyzer reports not issues, so I have a feeling dart doc has a different metric.

I am probably going to make the internal variables private anyways.

Also for the error it was an issue with the top level library names conflicting. I had signals_flutter twice for both the extended and non extended export.

I also just have been iterating on documentation and code coverage so it was also probably some small things like not being able to find the class referenced.