dlang-community / D-Scanner

Swiss-army knife for D source code
Boost Software License 1.0
242 stars 80 forks source link

Warn about accessing private members in documented `unittest`s #893

Open Bolpat opened 1 year ago

Bolpat commented 1 year ago

This was suggested to me by @Geod24 in https://issues.dlang.org/show_bug.cgi?id=21462

A unit test should not be accessing private members when it is documented; the same sequence of instructions won’t compile for a user of the module. If the documentation comment for the unit test starts with Private. (case insensitive) or is ditto and the referred documentation starts with Private., the warning is suppressed.

Geod24 commented 1 year ago

Actually, I'll add one condition: If the documented unittest is for a private symbol, no warning should be emitted.

Bolpat commented 1 year ago

If you like this, it can be extended to protected and/or package symbols. I’d strongly suggest to include protected with Protected. as the documentation keyword to mark this as intentional. Package is probably harder because package visibility can be qualified, and while it’s pretty clear what Private and Protected as part of the unit test documentation means, Package isn’t as clear.

Geod24 commented 1 year ago

I would not extend it to protected. Remember we want to minimize the amount of boilerplate here. protected is, to some extent, closer to public than to private (if the class is public). Let's start with private and see how well it works first.