README

PHP Doc Check 是一个自动化的命令行工具，用于确定哪些函数和方法可能需要更多的文档。

默认情况下，此脚本

• 如果非平凡函数没有文档块，则发出警告（得分 > 4）
• 如果复杂函数没有文档块，则发出错误（得分 > 6）

您可以通过从相对较高的限制开始，并逐渐降低这些限制，逐步提高项目的文档。

指标

• 认知复杂度 <默认> 用于查找阅读和理解复杂的函数。
• 圈复杂度 用于查找具有更传统算法的复杂函数。

安装

Composer

目前您必须安装测试版。

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

Phive

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

首次使用示例：vendor/bin/php-doc-check --exclude vendor ./

示例

没有文档块也可以（平凡方法）

public function get_title() : string{
    return strtoupper($this->title);
}

这可能需要一些解释

/**
 * 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：为什么即使没有注释，也想要警告或错误，无论复杂度如何？

A：您可以通过设置 --complexity-error-threshold 1 将此软件设置为对所有未文档化的函数发出警告。但是，如果您想强制文档，您可能需要查找与文档标准相结合的工具，如 php CodeSniffer。

Q：为什么没有关于复杂函数和重构的警告/错误，无论它们是否有 DocBlock？

A：您应该重构非常复杂的函数。但是，为复杂函数添加 DocBlock 往往更容易且更安全。此工具仅检查此类文档的存在。其他工具，如 php Mess Detector，可以帮助您限制复杂度。

问题

问题在 GitHub 跟踪器中：https://github.com/NielsdeBlaauw/php-doc-check/issues