For some historical reasons we currently offer two ways to track undocumented API:
- By using the "Public types, methods and fields (API) should be documented" rule (see RSPEC-1176)
- Or by using the "Public Documented API (%)" measure
And this leads to several annoying side effects :
- As always when you provide two ways to do the same thing, this creates some confusion on end-user side : should I use this way or this way ?
- As usual in SonarQube, using a global measure instead of a rule to track some code smells has several drawbacks :
- You have no way to track new undocumented API. And so in the same sprint you can add some new undocumented API and document some old ones without any awareness of what happens.
- That's pretty hard to clearly spot each undocumented API
- Most of the time users don't want to consider all public methods or classes as being an API and so this requires to slightly tune this definition by limiting the scope to some packages (based on regexp) and/or by excluding what can be considered as a getter/setter. But again if you want to have something consistent between the rule and the metric this requires to duplicate the configuration effort.
So time has come to fix this flaw by enforcing our users to use the rule in charge to track undocumented API instead of using the relating metrics: