Feature Request: Documentation Coverage Percentage

[Veraxus]

Would it be possible to get a feature that outputs comment coverage as a percentage? I want to be able to enforce documentation coverage the same way I enforce test coverage, and having the ability to run a command in CI that simply returns a PhpDoc coverage percentage would be incredible.

• Version used: 3.0.0-alpha1
• Install method: Composer
• php version: 7.2
• Operating system and version (e.g. Ubuntu 16.04, Windows 7): OSX High Sierra

[mvriel]

This is an interesting feature but requires some discussion since there is the question of how we could measure comment coverage and what acceptable thresholds are or how to configure these best.

Last #WeCamp18 (a coding retreat int he Netherlands) one team described documentation coverage as how many methods had an @see leading to a real page on the internet containing documentation. This is an interesting method but would cause quite a few @see tags in the code unless some smart algorithm is used somehow.

[in4s]

I think, at least basics: percantage of commented classes, methods, properties.

Veraxus, how is your percentage of test covearage work? (how does it measured?)

[Veraxus]

In my case, I require documentation for:

• Files
• Classes
• Properties
• Methods / Functions
  • Parameters
  • Return values
  • Throws / Exceptions

In my mind, each of these is worth 1 (equal weight by item, including sub-items like function params).

A partial documentation for any of these (e.g. a return without a note or a param without a type) is worth 0.5 while missing documentation is 0. The percentage would be calculated:

t = total possible documentable components
a = actual documented components

coverage = ( a / t ) / 100