function FunctionCommentSniff::process

Same name in this branch

1. 11.1.x vendor/squizlabs/php_codesniffer/src/Standards/MySource/Sniffs/Commenting/FunctionCommentSniff.php \PHP_CodeSniffer\Standards\MySource\Sniffs\Commenting\FunctionCommentSniff::process()
2. 11.1.x vendor/squizlabs/php_codesniffer/src/Standards/PEAR/Sniffs/Commenting/FunctionCommentSniff.php \PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting\FunctionCommentSniff::process()

Processes this test, when one of its tokens is encountered.

Parameters

\PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.:

int $stackPtr The position of the current token: in the stack passed in $tokens.

Return value

void

Overrides Sniff::process

File

vendor/drupal/coder/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php, line 75

Class

FunctionCommentSniff

Parses and verifies the doc comments for functions. Largely copied from PHP_CodeSniffer\Standards\Squiz\Sniffs\Commenting\FunctionCommentSniff.

Namespace

Drupal\Sniffs\Commenting

Code

public function process(File $phpcsFile, $stackPtr) {
    $tokens = $phpcsFile->getTokens();
    $ignore = Tokens::$methodPrefixes;
    $ignore[T_WHITESPACE] = T_WHITESPACE;
    $functionCodeStart = $stackPtr;
    for ($commentEnd = $stackPtr - 1; $commentEnd >= 0; $commentEnd--) {
        if (isset($ignore[$tokens[$commentEnd]['code']]) === true) {
            continue;
        }
        if ($tokens[$commentEnd]['code'] === T_ATTRIBUTE_END && isset($tokens[$commentEnd]['attribute_opener']) === true) {
            $commentEnd = $functionCodeStart = $tokens[$commentEnd]['attribute_opener'];
            continue;
        }
        break;
    }
    // Constructor methods are exempt from requiring a docblock.
    // @see https://www.drupal.org/project/coder/issues/3400560.
    $methodName = $phpcsFile->getDeclarationName($stackPtr);
    if ($methodName === '__construct' && $tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG && $tokens[$commentEnd]['code'] !== T_COMMENT) {
        return;
    }
    $beforeCommentEnd = $phpcsFile->findPrevious(Tokens::$emptyTokens, $commentEnd - 1, null, true);
    if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG && $tokens[$commentEnd]['code'] !== T_COMMENT || $beforeCommentEnd !== false && $tokens[$beforeCommentEnd]['line'] === $tokens[$commentEnd]['line']) {
        $fix = $phpcsFile->addFixableError('Missing function doc comment', $stackPtr, 'Missing');
        if ($fix === true) {
            $before = $phpcsFile->findNext(T_WHITESPACE, $commentEnd + 1, $stackPtr + 1, true);
            $phpcsFile->fixer
                ->addContentBefore($before, "/**\n *\n */\n");
        }
        return;
    }
    if ($tokens[$commentEnd]['code'] === T_COMMENT) {
        $fix = $phpcsFile->addFixableError('You must use "/**" style comments for a function comment', $stackPtr, 'WrongStyle');
        if ($fix === true) {
            // Convert the comment into a doc comment.
            $phpcsFile->fixer
                ->beginChangeset();
            $comment = '';
            for ($i = $commentEnd; $tokens[$i]['code'] === T_COMMENT; $i--) {
                $comment = ' *' . ltrim($tokens[$i]['content'], '/* ') . $comment;
                $phpcsFile->fixer
                    ->replaceToken($i, '');
            }
            $phpcsFile->fixer
                ->replaceToken($commentEnd, "/**\n" . rtrim($comment, "*/\n") . "\n */\n");
            $phpcsFile->fixer
                ->endChangeset();
        }
        return;
    }
    $commentStart = $tokens[$commentEnd]['comment_opener'];
    foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
        // This is a file comment, not a function comment.
        if ($tokens[$tag]['content'] === '@file') {
            $fix = $phpcsFile->addFixableError('Missing function doc comment', $stackPtr, 'Missing');
            if ($fix === true) {
                $before = $phpcsFile->findNext(T_WHITESPACE, $commentEnd + 1, $stackPtr + 1, true);
                $phpcsFile->fixer
                    ->addContentBefore($before, "/**\n *\n */\n");
            }
            return;
        }
        if ($tokens[$tag]['content'] === '@see') {
            // Make sure the tag isn't empty.
            $string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $tag, $commentEnd);
            if ($string === false || $tokens[$string]['line'] !== $tokens[$tag]['line']) {
                $error = 'Content missing for @see tag in function comment';
                $phpcsFile->addError($error, $tag, 'EmptySees');
            }
        }
    }
    
    //end foreach
    if ($tokens[$commentEnd]['line'] !== $tokens[$functionCodeStart]['line'] - 1) {
        $error = 'There must be no blank lines after the function comment';
        $fix = $phpcsFile->addFixableError($error, $commentEnd, 'SpacingAfter');
        if ($fix === true) {
            $phpcsFile->fixer
                ->replaceToken($commentEnd + 1, '');
        }
    }
    $this->processReturn($phpcsFile, $stackPtr, $commentStart);
    $this->processThrows($phpcsFile, $stackPtr, $commentStart);
    $this->processParams($phpcsFile, $stackPtr, $commentStart);
    $this->processSees($phpcsFile, $stackPtr, $commentStart);
}