Uses complexity metrics to determine which functions need documentation.
MIT License
PHP Doc Check is an automated command line tool to determine which functions and methods could use some more documentation.
By default this script:
You can gradually improve documenation on projects by starting with relatively high limits and slowly moving these limits down.
<default>
isFor now you have to install the beta version.
composer require --dev niels-de-blaauw/php-doc-check:^0.2.0@dev
phive install php-doc-check
$vendor/bin/php-doc-check -?
Usage: vendor/bin/php-doc-check [options] <directory> [<directory>...]
Options:
-x, --exclude <arg> Directories to exclude, without
slash
-f, --format <arg> Output format [text, json]
[default: text]
-o, --reportFile <arg> Send report output to a file
-m, --metric <arg> Metric to use for determining
complexity
[metrics.complexity.cognitive,
metrics.complexity.cyclomatic,
metrics.deprecated.category,
metrics.deprecated.subpackage,
metrics.complexity.length]
[default:
metrics.complexity.cognitive]
-w, --complexity-warning-threshold <arg> Cyclomatic complexity score which
is the lower bound for a warning
[default: 4]
-e, --complexity-error-threshold <arg> Cyclomatic complexity score which
is the lower bound for an error
[default: 6]
-$, --file-extension <arg> Valid file extensions to scan
[default: php]
-g, --grouping-method <arg> Allows different grouping of the
results list [file, none, metric,
severity, fileline] [default: file]
-s, --sorting-method <arg> Sorting for the results. Natural
sorts by name for groups and line
for findings. Value uses the
cumulative group score, and finding
score as sorting value. [natural,
value] [default: natural]
-i, --ignore-violations-on-exit Will exit with a zero code, even if
any violations are found
-a, --ignore-anonymous-functions Skip checks on anonymous functions
-?, --help Show this help and quit
-q, --quiet Don't show any output
Example first use: vendor/bin/php-doc-check --exclude vendor ./
This is fine without docblocks (trivial method)
public function get_title() : string{
return strtoupper($this->title);
}
This could use some explanation
/**
* Limits the length of the title to a normal sentence, because older titles
* tend to be longer then we can currently show.
*/
public function get_title() : string{
if(strlen($this->title) > 20 ){
if(strpos($this->title,'.') !== false && strpos($this->title,'.') < 20){
[$title] = explode('.', $this->title, 2);
}else{
$title = substr($this->title, 0, 17) . '...';
}
}else{
$title = $this->title;
}
return strtoupper($title);
}
Q: Why dont you want if there is no comment at all, regardless of complexity?
A: You can set this software to warn for all functions that are undocumented by
setting --complexity-error-threshold 1
. However, if you want to force
documentation, you probably want to look into a tool like php CodeSniffer
in combination with documentation standards.
Q: Why isn't there a warning/error about complex functions and refactoring, regardless if they have a DocBlock?
A: You should refactor very complex functions. However, adding DocBlocks for complex function is often easier and safer. This tool only checks the availability of this type of documentation. Other tools, like php Mess Detector, can help you limit complexity.
Issues are in the GitHub tracker: https://github.com/NielsdeBlaauw/php-doc-check/issues