Class documentation: remove redundancy #734
Description
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 <[email protected]>
* @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 <[email protected]>
* @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 <[email protected]>
* @since x.x.x (PHPCompatibility version in which the sniff was introduced)
*/Opinions ?