make @visibleForTesting equivalent to dartdoc's @nodoc tag

[jcollins-g]

@jacob314 suggested that @visibleForTesting could be made equivalent to the @nodoc tag and hide elements so tagged.

P3 because I'm not sure dartdoc is the right place to implement this, but I think the idea in general to align these is reasonable. It's a little tricky because dartdoc has to locate the special object in question (making me think of #1554) but if we decide it is a good idea it's definitely possible.

[chalin]

Maybe support defining aliases for @nodoc (rather than hardcode specific names), in the (newly introduced) dartdoc YAML config? /cc @kwalrath

[jcollins-g]

@chalin Yes, specifying annotations that should be treated as nodoc in dartdoc_options.yaml should work. Though if we really do want to allow specifying arbitrary ones we should fix #1554 first.

[BrennanGambling]

@jcollins-g If not this this would just adding an option to ignore @Nodoc tag to the command line tool work?

[jcollins-g]

@BrennanGambling Hi Brennan, I'm not sure I understand what "adding an option to ignore @Nodoc tag to the command line tool work" means here. Dartdoc already ignores @nodoc.

If you mean, add these via the command line, part of the problem from dartdoc's perspective is finding a way to specify which named object to hide. Users can create their own classes with the same name and without some special support (like that added in the fix to #1554) it's not easy to add support for arbitrary ones.

Increasing to P2 -- it seems like a good idea to do something about this even if we're not sure what yet.

[BrennanGambling]

@jcollins-g by "adding an option to ignore the @Nodoc tag" I mean a command line option/flag the will ignore the @Nodoc tag and not the comment. So in the default mode adding the @Nodoc tag to a comment would mean it would not appear in the documentation. but say calling dartdoc with a --ignore-nodoc-tag option would mean doc comments tagged with @Nodoc would still appear in the documentation. It would be very useful for making the public API documentation and then seperate documentation for internal use by the package developers.

[jcollins-g]

@BrennanGambling This is something we could do. It would have some impact on canonicalization and cross-linking between repos (because different runs of dartdoc with and without this flag would create different canonicalizations for different objects). Some loud warning to that effect if --link-to-remote is set seems like a good idea.

[rrousselGit]

I disagree here.
Testing APIs are public APIs.

I have packages which expose test-only APIs alongside other APIs. Those are intended to be used by users but just inside tests (due to being less safe and such).

An implicit nodoc here is counterproductive to that goal.