Uploaded image for project: 'Product Roadmaps'
  1. Product Roadmaps
  2. MMF-554

Stop providing two ways to track undocumented API

    Details

    • Type: MMF
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Labels:

      Description

      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:

      • The metrics "Public API", "Public Undocumented API" and "Public Documented API (%)" must be deprecated (see SONAR-8328) and should not be displayed anymore in the SonarQube UI
      • The SonarAnalyzer for Java must stop feeding those 3 metrics (see SONARJAVA-1916)

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                ann.campbell.2 Ann Campbell
                Reporter:
                freddy.mallet Freddy Mallet (Inactive)
              • Votes:
                1 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: