DocCommentSniff.php

<?php
/**
 * Ensures doc blocks follow basic formatting.
 *
 * @author    Greg Sherwood <gsherwood@squiz.net>
 * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
 */

namespace PHP_CodeSniffer\Standards\Generic\Sniffs\Commenting;

use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Sniffs\Sniff;

class DocCommentSniff implements Sniff
{

    /**
     * A list of tokenizers this sniff supports.
     *
     * @var array
     */
    public $supportedTokenizers = [
        'PHP',
        'JS',
    ];


    /**
     * Returns an array of tokens this test wants to listen for.
     *
     * @return array
     */
    public function register()
    {
        return [T_DOC_COMMENT_OPEN_TAG];

    }//end register()


    /**
     * Processes this test, when one of its tokens is encountered.
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token
     *                                               in the stack passed in $tokens.
     *
     * @return void
     */
    public function process(File $phpcsFile, $stackPtr)
    {
        $tokens = $phpcsFile->getTokens();

        if (isset($tokens[$stackPtr]['comment_closer']) === false
            || ($tokens[$tokens[$stackPtr]['comment_closer']]['content'] === ''
            && $tokens[$stackPtr]['comment_closer'] === ($phpcsFile->numTokens - 1))
        ) {
            // Don't process an unfinished comment during live coding.
            return;
        }

        $commentStart = $stackPtr;
        $commentEnd   = $tokens[$stackPtr]['comment_closer'];

        $empty = [
            T_DOC_COMMENT_WHITESPACE,
            T_DOC_COMMENT_STAR,
        ];

        $short = $phpcsFile->findNext($empty, ($stackPtr + 1), $commentEnd, true);
        if ($short === false) {
            // No content at all.
            $error = 'Doc comment is empty';
            $fix   = $phpcsFile->addFixableError($error, $stackPtr, 'Empty');

            if ($fix === true) {
                $phpcsFile->fixer->beginChangeset();
                for ($i = $commentStart; $i <= $commentEnd; $i++) {
                    $phpcsFile->fixer->replaceToken($i, '');
                }

                if (isset($tokens[($commentStart - 1)]) === true && isset($tokens[($commentEnd + 1)]) === true) {
                    $tokenBefore = $tokens[($commentStart - 1)];
                    $tokenAfter  = $tokens[($commentEnd + 1)];
                    if ($tokenBefore['code'] === T_WHITESPACE
                        && $tokenBefore['content'] === $phpcsFile->eolChar
                        && $tokenAfter['code'] === T_WHITESPACE
                        && $tokenAfter['content'] === $phpcsFile->eolChar
                    ) {
                        $phpcsFile->fixer->replaceToken(($commentStart - 1), '');
                    }
                }

                $phpcsFile->fixer->endChangeset();
            }

            return;
        }//end if

        // The first line of the comment should just be the /** code.
        if ($tokens[$short]['line'] === $tokens[$stackPtr]['line']) {
            $error = 'The open comment tag must be the only content on the line';
            $fix   = $phpcsFile->addFixableError($error, $stackPtr, 'ContentAfterOpen');
            if ($fix === true) {
                $phpcsFile->fixer->beginChangeset();
                $phpcsFile->fixer->addNewline($stackPtr);
                $phpcsFile->fixer->addContentBefore($short, '* ');
                $phpcsFile->fixer->endChangeset();
            }
        }

        // The last line of the comment should just be the */ code.
        $prev = $phpcsFile->findPrevious($empty, ($commentEnd - 1), $stackPtr, true);
        if ($tokens[$prev]['line'] === $tokens[$commentEnd]['line']) {
            $error = 'The close comment tag must be the only content on the line';
            $fix   = $phpcsFile->addFixableError($error, $commentEnd, 'ContentBeforeClose');
            if ($fix === true) {
                $phpcsFile->fixer->addNewlineBefore($commentEnd);
            }
        }

        // Check for additional blank lines at the end of the comment.
        if ($tokens[$prev]['line'] < ($tokens[$commentEnd]['line'] - 1)) {
            $error = 'Additional blank lines found at end of doc comment';
            $fix   = $phpcsFile->addFixableError($error, $commentEnd, 'SpacingAfter');
            if ($fix === true) {
                $phpcsFile->fixer->beginChangeset();
                for ($i = ($prev + 1); $i < $commentEnd; $i++) {
                    if ($tokens[($i + 1)]['line'] === $tokens[$commentEnd]['line']) {
                        break;
                    }

                    $phpcsFile->fixer->replaceToken($i, '');
                }

                $phpcsFile->fixer->endChangeset();
            }
        }

        // Check for a comment description.
        if ($tokens[$short]['code'] !== T_DOC_COMMENT_STRING) {
            $error = 'Missing short description in doc comment';
            $phpcsFile->addError($error, $stackPtr, 'MissingShort');
        } else {
            // No extra newline before short description.
            if ($tokens[$short]['line'] !== ($tokens[$stackPtr]['line'] + 1)) {
                $error = 'Doc comment short description must be on the first line';
                $fix   = $phpcsFile->addFixableError($error, $short, 'SpacingBeforeShort');
                if ($fix === true) {
                    $phpcsFile->fixer->beginChangeset();
                    for ($i = $stackPtr; $i < $short; $i++) {
                        if ($tokens[$i]['line'] === $tokens[$stackPtr]['line']) {
                            continue;
                        } else if ($tokens[$i]['line'] === $tokens[$short]['line']) {
                            break;
                        }

                        $phpcsFile->fixer->replaceToken($i, '');
                    }

                    $phpcsFile->fixer->endChangeset();
                }
            }

            // Account for the fact that a short description might cover
            // multiple lines.
            $shortContent = $tokens[$short]['content'];
            $shortEnd     = $short;
            for ($i = ($short + 1); $i < $commentEnd; $i++) {
                if ($tokens[$i]['code'] === T_DOC_COMMENT_STRING) {
                    if ($tokens[$i]['line'] === ($tokens[$shortEnd]['line'] + 1)) {
                        $shortContent .= $tokens[$i]['content'];
                        $shortEnd      = $i;
                    } else {
                        break;
                    }
                }
            }

            if (preg_match('/^\p{Ll}/u', $shortContent) === 1) {
                $error = 'Doc comment short description must start with a capital letter';
                $phpcsFile->addError($error, $short, 'ShortNotCapital');
            }

            $long = $phpcsFile->findNext($empty, ($shortEnd + 1), ($commentEnd - 1), true);
            if ($long !== false && $tokens[$long]['code'] === T_DOC_COMMENT_STRING) {
                if ($tokens[$long]['line'] !== ($tokens[$shortEnd]['line'] + 2)) {
                    $error = 'There must be exactly one blank line between descriptions in a doc comment';
                    $fix   = $phpcsFile->addFixableError($error, $long, 'SpacingBetween');
                    if ($fix === true) {
                        $phpcsFile->fixer->beginChangeset();
                        for ($i = ($shortEnd + 1); $i < $long; $i++) {
                            if ($tokens[$i]['line'] === $tokens[$shortEnd]['line']) {
                                continue;
                            } else if ($tokens[$i]['line'] === ($tokens[$long]['line'] - 1)) {
                                break;
                            }

                            $phpcsFile->fixer->replaceToken($i, '');
                        }

                        $phpcsFile->fixer->endChangeset();
                    }
                }

                if (preg_match('/^\p{Ll}/u', $tokens[$long]['content']) === 1) {
                    $error = 'Doc comment long description must start with a capital letter';
                    $phpcsFile->addError($error, $long, 'LongNotCapital');
                }
            }//end if
        }//end if

        if (empty($tokens[$commentStart]['comment_tags']) === true) {
            // No tags in the comment.
            return;
        }

        $indent = str_repeat(' ', $tokens[$stackPtr]['column']);

        $firstTag = $tokens[$commentStart]['comment_tags'][0];
        $prev     = $phpcsFile->findPrevious($empty, ($firstTag - 1), $stackPtr, true);
        if ($tokens[$firstTag]['line'] !== ($tokens[$prev]['line'] + 2)
            && $tokens[$prev]['code'] !== T_DOC_COMMENT_OPEN_TAG
        ) {
            $error = 'There must be exactly one blank line before the tags in a doc comment';
            $fix   = $phpcsFile->addFixableError($error, $firstTag, 'SpacingBeforeTags');
            if ($fix === true) {
                $phpcsFile->fixer->beginChangeset();
                for ($i = ($prev + 1); $i < $firstTag; $i++) {
                    if ($tokens[$i]['line'] === $tokens[$firstTag]['line']) {
                        break;
                    }

                    $phpcsFile->fixer->replaceToken($i, '');
                }

                $phpcsFile->fixer->addContent($prev, $phpcsFile->eolChar.$indent.'*'.$phpcsFile->eolChar);
                $phpcsFile->fixer->endChangeset();
            }
        }

        // Break out the tags into groups and check alignment within each.
        // A tag group is one where there are no blank lines between tags.
        // The param tag group is special as it requires all @param tags to be inside.
        $tagGroups    = [];
        $groupid      = 0;
        $paramGroupid = null;
        $firstTagAfterParams = null;
        foreach ($tokens[$commentStart]['comment_tags'] as $pos => $tag) {
            if ($pos > 0) {
                $prev = $phpcsFile->findPrevious(
                    T_DOC_COMMENT_STRING,
                    ($tag - 1),
                    $tokens[$commentStart]['comment_tags'][($pos - 1)]
                );

                if ($prev === false) {
                    $prev = $tokens[$commentStart]['comment_tags'][($pos - 1)];
                }

                if ($tokens[$prev]['line'] !== ($tokens[$tag]['line'] - 1)) {
                    $groupid++;
                }
            }

            if ($tokens[$tag]['content'] === '@param') {
                if ($paramGroupid !== null
                    && $paramGroupid !== $groupid
                ) {
                    $error = 'Parameter tags must be grouped together in a doc comment';
                    $fix   = $phpcsFile->addFixableError($error, $tag, 'ParamGroup');

                    if ($fix === true) {
                        $phpcsFile->fixer->beginChangeset();

                        $thisTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $tag, $commentStart, false, $phpcsFile->eolChar));

                        if (isset($tokens[$stackPtr]['comment_tags'][($pos + 1)]) === true) {
                            $nextTag          = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($tag + 1), $commentEnd);
                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $nextTag, $commentStart, false, $phpcsFile->eolChar));
                        } else {
                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $commentEnd, $commentStart, false, $phpcsFile->eolChar));
                        }

                        $thisTagContent = '';
                        for ($i = $thisTagLineStart; $i < $nextTagLineStart; $i++) {
                            if ($tokens[($i - 1)]['content'] === $phpcsFile->eolChar
                                && $tokens[$i]['content'] === $indent
                                && $tokens[($i + 1)]['content'] === '*'
                                && $tokens[($i + 2)]['content'] === $phpcsFile->eolChar
                            ) {
                                break;
                            }

                            $thisTagContent .= $tokens[$i]['content'];
                            $phpcsFile->fixer->replaceToken($i, '');
                        }

                        $insertionPointer = $phpcsFile->findPrevious(T_DOC_COMMENT_TAG, ($tag - 1), $commentStart, false, '@param');

                        while ($tokens[($insertionPointer - 1)]['content'] !== $phpcsFile->eolChar
                            || $tokens[$insertionPointer]['content'] !== $indent
                            || $tokens[($insertionPointer + 1)]['content'] !== '*'
                            || $tokens[($insertionPointer + 2)]['content'] !== $phpcsFile->eolChar
                        ) {
                            $insertionPointer++;

                            if (($insertionPointer + 2) >= $commentEnd) {
                                $insertionPointer = ($commentEnd - 1);
                                break;
                            }
                        }

                        $phpcsFile->fixer->addContentBefore($insertionPointer, $thisTagContent);

                        $phpcsFile->fixer->endChangeset();
                    }//end if
                }//end if

                if ($paramGroupid === null) {
                    $paramGroupid = $groupid;
                }
            } else if ($paramGroupid !== null && $firstTagAfterParams === null) {
                $firstTagAfterParams = $tag;
            }//end if

            $tagGroups[$groupid][] = $tag;
        }//end foreach

        foreach ($tagGroups as $groupid => $group) {
            $maxLength           = 0;
            $paddings            = [];
            $canFixNonParamGroup = true;
            foreach ($group as $pos => $tag) {
                if ($paramGroupid === $groupid
                    && $tokens[$tag]['content'] !== '@param'
                ) {
                    $error = 'Tag %s cannot be grouped with parameter tags in a doc comment';
                    $data  = [$tokens[$tag]['content']];

                    if ($canFixNonParamGroup === true) {
                        $canFixNonParamGroup = $phpcsFile->addFixableError($error, $tag, 'NonParamGroup', $data);
                    } else {
                        $phpcsFile->addError($error, $tag, 'NonParamGroup', $data);
                    }

                    if ($canFixNonParamGroup === true) {
                        $phpcsFile->fixer->beginChangeset();

                        if ($pos > 0) {
                            $thisTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $tag, $commentStart, false, $phpcsFile->eolChar));
                            $phpcsFile->fixer->addContentBefore($thisTagLineStart, $indent.'*'.$phpcsFile->eolChar);
                        } else {
                            $nextTag          = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($tag + 1), $commentEnd);
                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $nextTag, $commentStart, false, $phpcsFile->eolChar));
                            $phpcsFile->fixer->addContentBefore($nextTagLineStart, $indent.'*'.$phpcsFile->eolChar);
                        }

                        $phpcsFile->fixer->endChangeset();
                        $canFixNonParamGroup = false;
                    }
                }//end if

                $tagLength = $tokens[$tag]['length'];
                if ($tagLength > $maxLength) {
                    $maxLength = $tagLength;
                }

                // Check for a value. No value means no padding needed.
                $string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $tag, $commentEnd);
                if ($string !== false && $tokens[$string]['line'] === $tokens[$tag]['line']) {
                    $paddings[$tag] = $tokens[($tag + 1)]['length'];
                }
            }//end foreach

            // Check that there was single blank line after the tag block
            // but account for a multi-line tag comments.
            $lastTag = $group[$pos];
            $next    = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($lastTag + 3), $commentEnd);
            if ($next !== false) {
                $prev = $phpcsFile->findPrevious([T_DOC_COMMENT_TAG, T_DOC_COMMENT_STRING], ($next - 1), $commentStart);
                if ($tokens[$next]['line'] !== ($tokens[$prev]['line'] + 2)) {
                    $error = 'There must be a single blank line after a tag group';
                    $fix   = $phpcsFile->addFixableError($error, $lastTag, 'SpacingAfterTagGroup');
                    if ($fix === true) {
                        $phpcsFile->fixer->beginChangeset();
                        for ($i = ($prev + 1); $i < $next; $i++) {
                            if ($tokens[$i]['line'] === $tokens[$next]['line']) {
                                break;
                            }

                            $phpcsFile->fixer->replaceToken($i, '');
                        }

                        $phpcsFile->fixer->addContent($prev, $phpcsFile->eolChar.$indent.'*'.$phpcsFile->eolChar);
                        $phpcsFile->fixer->endChangeset();
                    }
                }
            }//end if

            // Now check paddings.
            foreach ($paddings as $tag => $padding) {
                $required = ($maxLength - $tokens[$tag]['length'] + 1);

                if ($padding !== $required) {
                    $error = 'Tag value for %s tag indented incorrectly; expected %s spaces but found %s';
                    $data  = [
                        $tokens[$tag]['content'],
                        $required,
                        $padding,
                    ];

                    $fix = $phpcsFile->addFixableError($error, ($tag + 1), 'TagValueIndent', $data);
                    if ($fix === true) {
                        $phpcsFile->fixer->replaceToken(($tag + 1), str_repeat(' ', $required));
                    }
                }
            }
        }//end foreach

        // If there is a param group, it needs to be first.
        if ($paramGroupid !== null && $paramGroupid !== 0) {
            $error = 'Parameter tags must be defined first in a doc comment';
            $fix   = $phpcsFile->addFixableError($error, $tagGroups[$paramGroupid][0], 'ParamNotFirst');

            if ($fix === true) {
                $phpcsFile->fixer->beginChangeset();

                $firstTag      = $phpcsFile->findNext(T_DOC_COMMENT_TAG, $stackPtr, $commentEnd);
                $firstParamTag = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($firstTag + 1), $commentEnd, false, '@param');
                if ($firstTagAfterParams === null) {
                    $firstTagAfterParams = $commentEnd;
                }

                $lineBetween = ($tokens[$firstParamTag]['line'] - 1);

                $tagGroupOne = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $firstTag, $commentStart, false, $phpcsFile->eolChar));
                $tagGroupTwo = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $firstParamTag, $commentStart, false, $phpcsFile->eolChar));
                $markerThree = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $firstTagAfterParams, $commentStart, false, $phpcsFile->eolChar));

                $otherContent = $tokens[$tagGroupOne]['content'];
                for ($i = ($tagGroupOne + 1); $i < $tagGroupTwo; $i++) {
                    if ($tokens[$i]['line'] === $lineBetween) {
                        break;
                    }

                    $otherContent .= $tokens[$i]['content'];
                    $phpcsFile->fixer->replaceToken($i, '');
                }

                $paramContent = $tokens[$tagGroupTwo]['content'];
                for ($i = ($tagGroupTwo + 1); $i < $markerThree; $i++) {
                    $paramContent .= $tokens[$i]['content'];
                    $phpcsFile->fixer->replaceToken($i, '');
                }

                $phpcsFile->fixer->replaceToken($tagGroupOne, $paramContent);
                $phpcsFile->fixer->replaceToken($tagGroupTwo, $otherContent);

                $phpcsFile->fixer->endChangeset();
            }//end if
        }//end if

        $foundTags = [];
        foreach ($tokens[$stackPtr]['comment_tags'] as $pos => $tag) {
            $tagName = $tokens[$tag]['content'];
            if (isset($foundTags[$tagName]) === true) {
                $lastTag = $tokens[$stackPtr]['comment_tags'][($pos - 1)];
                if ($tokens[$lastTag]['content'] !== $tagName) {
                    $error = 'Tags must be grouped together in a doc comment';
                    $fix   = $phpcsFile->addFixableError($error, $tag, 'TagsNotGrouped');

                    if ($fix === true) {
                        $phpcsFile->fixer->beginChangeset();

                        $prevTag          = $phpcsFile->findPrevious(T_DOC_COMMENT_TAG, ($tag - 1), $commentStart);
                        $prevTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $prevTag, $commentStart, false, $phpcsFile->eolChar));
                        $thisTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $tag, $commentStart, false, $phpcsFile->eolChar));

                        if (isset($tokens[$stackPtr]['comment_tags'][($pos + 1)]) === true) {
                            $nextTag          = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($tag + 1), $commentEnd);
                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $nextTag, $commentStart, false, $phpcsFile->eolChar));
                        } else {
                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $commentEnd, $commentStart, false, $phpcsFile->eolChar));
                        }

                        $prevTagContent = $tokens[$prevTagLineStart]['content'];
                        for ($i = ($prevTagLineStart + 1); $i < $thisTagLineStart; $i++) {
                            $prevTagContent .= $tokens[$i]['content'];
                            $phpcsFile->fixer->replaceToken($i, '');
                        }

                        $thisTagContent = $tokens[$thisTagLineStart]['content'];
                        for ($i = ($thisTagLineStart + 1); $i < $nextTagLineStart; $i++) {
                            $thisTagContent .= $tokens[$i]['content'];
                            $phpcsFile->fixer->replaceToken($i, '');
                        }

                        $phpcsFile->fixer->replaceToken($prevTagLineStart, $thisTagContent);
                        $phpcsFile->fixer->replaceToken($thisTagLineStart, $prevTagContent);

                        $phpcsFile->fixer->endChangeset();
                    }//end if
                }//end if

                continue;
            }//end if

            $foundTags[$tagName] = true;
        }//end foreach

    }//end process()


}//end class