BestIt\Sniffs\Commenting\MethodDocSniff

Complexity

Total Complexity

21

Size/Duplication

Total Lines	227
Duplicated Lines	11.89 %

Coupling/Cohesion

Components	0
Dependencies	1

Test Coverage

Coverage

96.23%

Importance

Changes	1
Bugs	0	Features	0

2 Methods

Rating	Name	Duplication	Size	Complexity
A	register()	0	4	1
F	process()	27	85	20

<?php

declare(strict_types=1);


namespace BestIt\Sniffs\Commenting;

use PHP_CodeSniffer_File;
use PHP_CodeSniffer_Sniff;

/**
 * This Sniff checks the method phpdoc
 *
 * It is a modified version of the Generic DocCommentSniff adjusted for the bestit codestyle
 *
 * @package BestIt\Sniffs\Commenting
 *
 * @author Nils Hardeweg <nils.hardeweg@bestit-online.de>
 */
class MethodDocSniff implements PHP_CodeSniffer_Sniff
{
    #region constants
    /**
     * Code for an empty doc block
     *
     * @var string
     */
    const CODE_EMPTY = 'Empty';

    /**
     * Message for an empty doc block
     *
     * @var string
     */
    const MESSAGE_DOC_EMPTY = 'Doc comment is empty';

    /**
     * Code for a Spacing Error after the Summary
     *
     * @var string
     */
    const CODE_SPACING_AFTER = 'SpacingAfter';

    /**
     * Message for a Spacing Error after the Summary
     *
     * @var string
     */
    const MESSAGE_SPACING_AFTER = 'Additional blank lines found at end of doc comment';

    /**
     * Code for missing spacing between descriptions
     *
     * @var string
     */
    const CODE_SPACING_BETWEEN = 'SpacingBetween';

    /**
     * Message for missing spacing between descriptions
     *
     * @var string
     */
    const MESSAGE_SPACING_BETWEEN = 'There must be exactly one blank line between descriptions in a doc comment';

    /**
     * Code for missing spacing before the tags
     *
     * @var string
     */
    const CODE_SPACING_BEFORE_TAGS = 'SpacingBeforeTags';

    /**
     * Message for missing spacing before the tags
     *
     * @var string
     */
    const MESSAGE_SPACING_BEFORE_TAGS = 'There must be exactly one blank line before the tags in a doc comment';

    /**
     * Code for missing short description (Summary)
     *
     * @var string
     */
    const CODE_MISSING_SHORT = 'MissingShort';

    /**
     * Message for missing short description (Summary)
     *
     * @var string
     */
    const MESSAGE_MISSING_SHORT = 'Missing short description in doc comment';

    /**
     * Code for not capitalized short description
     *
     * @var string
     */
    const CODE_SHORT_NOT_CAPITAL = 'ShortNotCapital';

    /**
     * Message for not capitalized short description
     *
     * @var string
     */
    const MESSAGE_SHORT_NOT_CAPITAL = 'Doc comment short description must start with a capital letter';

    /**
     * Code for not Capitalized long description
     *
     * @var string
     */
    const CODE_LONG_NOT_CAPITAL = 'LongNotCapital';

    /**
     * Message for not Capitalized long description
     *
     * @var string
     */
    const MESSAGE_LONG_NOT_CAPITAL = 'Doc comment long description must start with a capital letter';

    /**
     * Code for empty lines before the short description
     *
     * @var string
     */
    const CODE_SPACING_BEFORE_SHORT = 'SpacingBeforeShort';

    /**
     * Message for empty lines before the short description
     *
     * @var string
     */
    const MESSAGE_CODE_SPACING_BEFORE = 'Doc comment short description must be on the first line';
    #endregion

    /**
     * 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];
    }

    /**
     * Processes this test, when one of its tokens is encountered.
     *
     * @param PHP_CodeSniffer_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(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
    {
        $tokens = $phpcsFile->getTokens();
        $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 = self::MESSAGE_DOC_EMPTY;
            $phpcsFile->addError($error, $stackPtr, self::CODE_EMPTY);
            return;
        }

        // The last line of the comment should just be the */ code.
        $prev = $phpcsFile->findPrevious($empty, $commentEnd - 1, $stackPtr, true);

        // Check for additional blank lines at the end of the comment.
        if ($tokens[$prev]['line'] < ($tokens[$commentEnd]['line'] - 1)) {

This code seems to be duplicated across your project.

            $error = self::MESSAGE_SPACING_AFTER;
            $phpcsFile->addError($error, $commentEnd, self::CODE_SPACING_AFTER);
        }

        // Check for a comment description.
        if ($tokens[$short]['code'] !== T_DOC_COMMENT_STRING

This code seems to be duplicated across your project.

            && $tokens[$short]['content'] !== '@inheritdoc'
            && $tokens[$short]['content'] !== '@var') {
            $error = self::MESSAGE_MISSING_SHORT;
            $phpcsFile->addError($error, $stackPtr, self::CODE_MISSING_SHORT);
            return;
        }

        // No extra newline before short description.
        if ($tokens[$short]['line'] !== ($tokens[$stackPtr]['line'] + 1) && $tokens[$short]['content'] !== '@var') {

This code seems to be duplicated across your project.

            $error = self::MESSAGE_CODE_SPACING_BEFORE;
            $phpcsFile->addError($error, $short, self::CODE_SPACING_BEFORE_SHORT);
        }

        $shortContent = $tokens[$short]['content'];
        /** @var int $shortEnd */
        $shortEnd = $short;

        if (preg_match('/^\p{Ll}/u', $shortContent) === 1) {
            $error = self::MESSAGE_SHORT_NOT_CAPITAL;
            $phpcsFile->addError($error, $short, self::CODE_SHORT_NOT_CAPITAL);
        }

        $long = $phpcsFile->findNext($empty, $shortEnd + 1, $commentEnd - 1, true);
        if ($long !== false && $tokens[$long]['code'] === T_DOC_COMMENT_STRING) {
            if (preg_match('/^\p{Ll}/u', $tokens[$long]['content']) === 1) {

This code seems to be duplicated across your project.

                $error = self::MESSAGE_LONG_NOT_CAPITAL;
                $phpcsFile->addError($error, $long, self::CODE_LONG_NOT_CAPITAL);
            }
        }

        $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)) {

This code seems to be duplicated across your project.

                $error = self::MESSAGE_SPACING_BETWEEN;
                $phpcsFile->addError($error, $long, self::CODE_SPACING_BETWEEN);
            }

            if (preg_match('/^\p{Ll}/u', $tokens[$long]['content']) === 1) {

This code seems to be duplicated across your project.

                $error = self::MESSAGE_LONG_NOT_CAPITAL;
                $phpcsFile->addError($error, $long, self::CODE_LONG_NOT_CAPITAL);
            }
        }

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

        $firstTag = $tokens[$commentStart]['comment_tags'][0];
        $prev = $phpcsFile->findPrevious($empty, $firstTag - 1, $stackPtr, true);
        if ($tokens[$firstTag]['line'] !== ($tokens[$prev]['line'] + 2)
            && $tokens[$short]['content'] !== '@inheritdoc'
            && $tokens[$short]['content'] !== '@var'
        ) {
            $error = self::MESSAGE_SPACING_BEFORE_TAGS;
            $phpcsFile->addError($error, $firstTag, self::CODE_SPACING_BEFORE_TAGS);
        }
    }
}