johnbillion / php-docs-standards
PHPUnit tests for documentation standards of PHP functions and methods.
Installs: 8 280
Dependents: 0
Suggesters: 0
Security: 0
Stars: 24
Watchers: 4
Forks: 4
Open Issues: 5
Requires
- php: >=7
- phpdocumentor/reflection-docblock: ~3.0 || ~4.0 || ~5.0
Requires (Dev)
- phpunit/phpunit: ^7
README
PHP Documentation Standards Tests
This abstract PHPUnit test case tests the standards and correctness of the inline documentation of your PHP functions and methods.
What's tested?
- The docblock should not be missing.
- The docblock description should not be empty.
- The number of
@param
docs should match the actual number of parameters. - The
@param
description for each parameter should not be empty. - The
@param
name for each parameter should be correct. - The
@param
type hint for each parameter should be correct. - The
@param
description for optional parameters should state that it is optional. - The
@param
description for required parameters should not state that it is optional. - The
@param
description for each parameter should state its default value, where appropriate.
Class-level docblocks are not tested.
Installation
Requirements:
- PHP 7 or 8
- PHPUnit 7 or higher
Add the package to your project's dev dependencies using Composer:
composer require johnbillion/php-docs-standards --dev
In your unit test bootstrap file, include the Composer autoloader. This will look something like this:
require dirname( dirname( __DIR__ ) ) . '/vendor/autoload.php';
Usage
Add a new test class to your test suite that extends the docs standards test case. The two abstract methods that need to
be implemented are getTestFunctions()
and getTestClasses()
. These methods return an array of function names and
class names, respectively, which are to be run through the test suite to test their documentation standards.
The functions and classes must be loaded (or available for autoloading) in the current request.
<?php class TestMyDocsStandards extends \Johnbillion\DocsStandards\TestCase { /** * Return an array of function names that will be run through the test suite. * * @return array Function names to test. */ protected function getTestFunctions() { return array( 'my_function_1', 'my_function_2', ); } /** * Return an array of class names whose methods will be run through the test suite. * * @return array Class names to test. */ protected function getTestClasses() { return array( 'My_Class_1', 'My_Class_2', ); } }
Why is this a unit test instead of a sniffer?
This was originally built to help the WordPress documentation team improve the documentation standards, and at the time the fastest way for me to implement it was as a unit test. It could also be a sniffer, if someone wanted to convert it.
License: GPLv2 or later
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.