1<?php
2/**
3 * Parses and verifies the doc comments for classes.
4 *
5 * PHP version 5
6 *
7 * @category  PHP
8 * @package   PHP_CodeSniffer
9 * @author    Greg Sherwood <gsherwood@squiz.net>
10 * @author    Marc McIntyre <mmcintyre@squiz.net>
11 * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
12 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
13 * @link      http://pear.php.net/package/PHP_CodeSniffer
14 */
15
16/**
17 * Parses and verifies the doc comments for classes.
18 *
19 * @category  PHP
20 * @package   PHP_CodeSniffer
21 * @author    Greg Sherwood <gsherwood@squiz.net>
22 * @author    Marc McIntyre <mmcintyre@squiz.net>
23 * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
24 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
25 * @version   Release: @package_version@
26 * @link      http://pear.php.net/package/PHP_CodeSniffer
27 */
28class PEAR_Sniffs_Commenting_ClassCommentSniff extends PEAR_Sniffs_Commenting_FileCommentSniff
29{
30
31
32    /**
33     * Returns an array of tokens this test wants to listen for.
34     *
35     * @return array
36     */
37    public function register()
38    {
39        return array(
40                T_CLASS,
41                T_INTERFACE,
42                T_TRAIT,
43               );
44
45    }//end register()
46
47
48    /**
49     * Processes this test, when one of its tokens is encountered.
50     *
51     * @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
52     * @param int                  $stackPtr  The position of the current token
53     *                                        in the stack passed in $tokens.
54     *
55     * @return void
56     */
57    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
58    {
59        $this->currentFile = $phpcsFile;
60
61        $tokens    = $phpcsFile->getTokens();
62        $type      = strtolower($tokens[$stackPtr]['content']);
63        $errorData = array($type);
64
65        $find   = PHP_CodeSniffer_Tokens::$methodPrefixes;
66        $find[] = T_WHITESPACE;
67
68        $commentEnd = $phpcsFile->findPrevious($find, ($stackPtr - 1), null, true);
69        if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG
70            && $tokens[$commentEnd]['code'] !== T_COMMENT
71        ) {
72            $phpcsFile->addError('Missing class doc comment', $stackPtr, 'Missing');
73            $phpcsFile->recordMetric($stackPtr, 'Class has doc comment', 'no');
74            return;
75        }
76
77        $phpcsFile->recordMetric($stackPtr, 'Class has doc comment', 'yes');
78
79        if ($tokens[$commentEnd]['code'] === T_COMMENT) {
80            $phpcsFile->addError('You must use "/**" style comments for a class comment', $stackPtr, 'WrongStyle');
81            return;
82        }
83
84        // Check each tag.
85        $this->processTags($phpcsFile, $stackPtr, $tokens[$commentEnd]['comment_opener']);
86
87    }//end process()
88
89
90    /**
91     * Process the version tag.
92     *
93     * @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
94     * @param array                $tags      The tokens for these tags.
95     *
96     * @return void
97     */
98    protected function processVersion(PHP_CodeSniffer_File $phpcsFile, array $tags)
99    {
100        $tokens = $phpcsFile->getTokens();
101        foreach ($tags as $tag) {
102            if ($tokens[($tag + 2)]['code'] !== T_DOC_COMMENT_STRING) {
103                // No content.
104                continue;
105            }
106
107            $content = $tokens[($tag + 2)]['content'];
108            if ((strstr($content, 'Release:') === false)) {
109                $error = 'Invalid version "%s" in doc comment; consider "Release: <package_version>" instead';
110                $data  = array($content);
111                $phpcsFile->addWarning($error, $tag, 'InvalidVersion', $data);
112            }
113        }
114
115    }//end processVersion()
116
117
118}//end class
119