nielsdeblaauw / php-doc-check Goto Github PK

Uses complexity metrics to determine which functions need documentation.

License: MIT License

PHP 100.00%

php ci automated-testing docblock cyclomatic-complexity hacktoberfest score metrics docblocks

php-doc-check's Introduction

php-doc-check

PHP Doc Check is an automated command line tool to determine which functions and methods could use some more documentation.

By default this script:

Emits a warning if there is no docblock for non trivial functions (score > 4)
Emits an error if there is no docblock for complex functions (score > 6)

You can gradually improve documenation on projects by starting with relatively high limits and slowly moving these limits down.

Metrics

Cognitive Complexity <default> is used to find functions that are complex to read and understand.
Cyclomatic Complexity is used to find complex functions with a more traditionl algorithm.

Installation

Composer

For now you have to install the beta version.

composer require --dev niels-de-blaauw/php-doc-check:^0.2.0@dev

Phive

phive install php-doc-check

Usage

$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 ./

Examples

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);
}

FAQ

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

Issues are in the GitHub tracker: https://github.com/NielsdeBlaauw/php-doc-check/issues

php-doc-check's People

Contributors

Stargazers

Watchers

Forkers

someonewithpc nikserg menno-ll

php-doc-check's Issues

Use getopt-php for argument parsing

Allows for a better usage interface then the current library https://getopt-php.github.io/getopt-php/

Custom sorting of groups

Requires implementation of #28 first. Groups can be sorted by either cumulative score of everything in the group or groupname (filename, error severity, etc.).

Add defaults to help text

@subpackage is deprecated

Type hints array should have DocBlock describing array type

Mismatching @param type and type hint in code

Mismatching docblock return type and method function return hint

Code has changed (significantly), but the DocBlock has not

If we can make some kind of snapshot of the docblocks for a function/method at a certain time, we can see which documentation has not been updated when the function is changed.

This would include the following steps:

Edit function with a docblock.
Run php-doc-check
If the functions meet a complexity metric: php-doc-check will compare the current docblock and function (length or complexity) to what is saved in the snapshot.
3.a. If the DocBlock is the same as the one in the snapshot: error that the DocBlock has not been updated.
3.b. If the DocBlock has changed, update the snapshot with the new docblock and filelength.
Manually edit the DocBlocks that have errored where applicable
Goto step 3 until all errors have been removed, or all the docblocks for all remaining errors are still descriptive of the function and origin of the code.
If remaining errors don't require changes: manually regenerate snapshot.
Commit changes and snapshot.

@package is equal to namespace

Allow for custom groupings

This allows users to group the findings to create their own overviews. Potential groups:

filename
severity
originating metric/rule
filename+starting line of method
none, everything is put into a single group

Sign Phar with GPG Signature

Function length metric

Add a metric for very long lineair functions and method that might not trigger complexity warnings.

Add metadata to json format

Allow for scope level exclusion

I only care about public methods and non-internal protected methods.

Anyway to only include these in the report?

Phar in releases

Hello,

I want to use this tool but I don't want to pollute my composer.json file. I've taken into habit to use the phar version of static analyzers (phan, phpstan, psalm, phpdoc…) so I'm sure I'll never run into dependencies clash.

Please consider releasing a (signed) phar archive :)

Cheers,
~Nico

URL in DocBlock is not @link or @see

Add unit tests

Catch parsing errors for invalid files

PHP-Parser throws an error exception when a php file being parsed is not valid.

Example:

Fatal error: Uncaught PhpParser\Error: Namespace declaration statement has to be the very first statement in the script on line 8 in [...]

@see references an @deprecated function but is not deprecated itself

Comments for anonymous functions not detected

Comments of anonymous functions are not always detected.

Redesign analysis pipeline

Allow for method level exclusions

Either using comments, or using an output message filter like phpstan does?

Allow for file level exclusions

Multiple metrics at once

Allow for checking multiple metrics at once. This allows the user to choose their own set of checks to run.

Use FQSEN

http://docs.phpdoc.org/glossary.html#term-fqsen

Add travis

Add PHP Mess Detector

@category is deprecated

Use 'Cognitive Complexity' in addition to Cyclic Complexity metric

https://www.tomasvotruba.cz/blog/2018/05/21/is-your-code-readable-by-humans-cognitive-complexity-tells-you/

Thanks to /u/Tomas_Votruba.

Parser error

There is some failure half through analysis and it throws the following exception:

.PHP Fatal error: Uncaught PhpParser\Error: Unexpected null byte on line 1 in ...vendor/nikic/php-parser/lib/PhpParser/Lexer.php:100

Custom sorting inside groups

Allows the user to either set the score/weight of a finding or the line number as sort order. Defaults to line number for backward compatibility.

Add coverage

@deprecated with no @see in the docblock

http://docs.phpdoc.org/references/phpdoc/tags/deprecated.html

Use humbug/box to build phar instead of kherge/box

The humbug form seems better maintained.

Add --ansi option to force table output when not running in a TTY

I looked through the code but wasn't able to figure out where the difference comes from, but when running this command from a git pre-commit hook, docker exec -it fails with the error the input device is not a TTY, and without the -it option, the output is not formatted into tables.

Tools like PHPStan and PHP-CS-fixer have a --ansi/--no-ansi option which would be helpful here.

I managed to work around this by running the command with < /dev/tty.

Specifically, the following:

make doc-check < /dev/tty
# where this make target runs bin/php-doc-check
# which runs:
docker exec -it container /path/vendor/bin/php-doc-check folders