At this moment, there is redundancy (duplication) of information in the File and Class docblocks and also some inconsistency.
I'd like to propose to clean this up.
Current pattern used:
/**
* \PHPCompatibility\Sniffs\Category\SniffName.
*
* PHP version x.x (version the change the sniff targets applies to)
*
* @category PHP
* @package PHPCompatibility
* @author Author Name <author@email.com>
* @copyright ... (sometimes)
*/
namespace PHPCompatibility\Sniffs\Category;
use PHPCompatibility\Sniff;
use PHP_CodeSniffer_Tokens as Tokens;
/**
* \PHPCompatibility\Sniffs\Category\SniffName.
*
* Description of the change in PHP.
*
* PHP version x.x (version the change the sniff targets applies to)
*
* @category PHP
* @package PHPCompatibility
* @author Author Name <author@email.com>
* @copyright ... (sometimes)
*/
Proposed cleaned up docblock patterns:
/**
* PHPCompatibility, an external standard for PHP_CodeSniffer.
*
* @package PHPCompatibility
* @link https://github.com/PHPCompatibility/PHPCompatibility
* @license https://opensource.org/licenses/LGPL-3.0 LGPL3
*/
namespace PHPCompatibility\Sniffs\Category;
use PHPCompatibility\Sniff;
use PHP_CodeSniffer_Tokens as Tokens;
/**
* Short description or SniffName (without the `Sniff` part and word separated with spaces).
*
* Longer description of the change in PHP.
*
* PHP version x.x (version the change the sniff targets applies to)
*
* @author Author Name <author@email.com>
* @since x.x.x (PHPCompatibility version in which the sniff was introduced)
*/
Opinions ?
At this moment, there is redundancy (duplication) of information in the File and Class docblocks and also some inconsistency.
I'd like to propose to clean this up.
Current pattern used:
Proposed cleaned up docblock patterns:
Opinions ?