DocDescriptionHelper::fixDescriptionUcFirst() - Code Metrics - Inspection of "DocBlocks" - bestit/PHP_CodeSniffer - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Pull Request — master (#19)

unknown

created 2017-08-04 07:49 UTC

DocDescriptionHelper::fixDescriptionUcFirst() A

↳ Parent: DocDescriptionHelper

Complexity

Conditions	1
Paths	1

Size

Total Lines	13
Code Lines	7

Duplication

Lines	13
Ratio	100 %

Code Coverage

Tests	8
CRAP Score	1

Importance

Changes

Metric	Value
dl	13
loc	13
ccs	8
cts	8
cp	1
rs	9.4285
c	0
b	0
f	0
cc	1
eloc	7
nc	1
nop	1
crap	1

<?php

declare(strict_types=1);

namespace BestIt\CodeSniffer\Helper;

use BestIt\CodeSniffer\File;
use BestIt\Sniffs\Commenting\AbstractDocSniff;

/**
 * Class DocDescriptionHelper
 *
 * @package BestIt\Helper
 * @author Nick Lubisch <[email protected]>
 */
class DocDescriptionHelper
{
    /**
     * The php code sniffer file.
     *
     * @var File
     */
    private $file;

    /**
     * The doc comment helper.
     *
     * @var DocHelper
     */
    private $docHelper;

    /**
     * The token stack of the cs file.
     *
     * @var array
     */
    private $tokens;

    /**
     * The doc comment summary helper.
     *
     * @var DocSummaryHelper
     */
    private $summaryHelper;

    /**
     * Indicator if a description is required.
     *
     * @var bool
     */
    private $descriptionRequired;

    /**
     * DocSummaryHelper constructor.
     *
     * @param File $file The php cs file
     * @param DocHelper $docHelper The doc comment helper
     * @param DocSummaryHelper $summaryHelper The doc comment summary helper
     */
    public function __construct(File $file, DocHelper $docHelper, DocSummaryHelper $summaryHelper)
    {
        $this->file = $file;
        $this->tokens = $file->getTokens();
        $this->docHelper = $docHelper;
        $this->summaryHelper = $summaryHelper;
    }

    /**
     * Checks for comment description.
     *
     * @param bool $descriptionRequired Indicator if the description is required.
     *
     * @return void
     */
    public function checkCommentDescription(bool $descriptionRequired): void
    {
        $this->descriptionRequired = $descriptionRequired;

        $commentStartToken = $this->docHelper->getCommentStartToken();
        $commentEndToken = $this->docHelper->getCommentEndToken();

        $summaryPtr = $this->summaryHelper->getCommentSummaryPointer();

        if ($summaryPtr === -1) {
            return;
        }

        $hasTags = count($commentStartToken['comment_tags']) > 0;

        $descriptionStartPtr = $this->getCommentDescriptionStartPointer();

        if ($descriptionStartPtr === -1) {
            $this->addDescriptionNotFoundError($summaryPtr);

            return;
        }

        $descriptionEndPtr = $this->getCommentDescriptionEndPointer();
        $descEndToken = $this->tokens[$descriptionEndPtr];

        $this->checkCommentDescriptionUcFirst($descriptionStartPtr);
        $this->checkCommentDescriptionLineLength($descriptionStartPtr, $descriptionEndPtr);

        //Fix no or too much lines after description.
        $toLine = $commentEndToken['line'];
        $expectedLines = 0;

        if ($hasTags) {
            $firstTagPtr = array_shift($commentStartToken['comment_tags']);
            $firstTagToken = $this->tokens[$firstTagPtr];
            $toLine = $firstTagToken['line'];

            $expectedLines = 1;
        }

        $diffLines = $toLine - $descEndToken['line'] - 1;

        if ($diffLines === $expectedLines) {
            return;
        }

        if ($diffLines < $expectedLines && $hasTags) {
            $fixNoLine = $this->file->addFixableError(
                AbstractDocSniff::MESSAGE_NO_LINE_AFTER_DESCRIPTION,
                $descriptionEndPtr,
                AbstractDocSniff::CODE_NO_LINE_AFTER_DESCRIPTION
            );

            if ($fixNoLine) {
                $this->fixNoLineAfterDescription();
            }

            return;
        }

        $fixMuchLines = $this->file->addFixableError(
            AbstractDocSniff::MESSAGE_MUCH_LINES_AFTER_DESCRIPTION,
            $descriptionEndPtr,
            AbstractDocSniff::CODE_MUCH_LINES_AFTER_DESCRIPTION
        );

        if ($fixMuchLines) {
            $this->fixMuchLinesAfterDescription($descEndToken['line'] + 1, $toLine - 1);
        }
    }

    /**
     * Checks if the description starts with a capital letter.
     *
     * @param int $descriptionStartPtr Pointer to the start of the description.
     *
     * @return void
     */
    private function checkCommentDescriptionUcFirst(int $descriptionStartPtr): void
    {
        $descStartToken = $this->tokens[$descriptionStartPtr];

        $descriptionContent = $descStartToken['content'];

        if (ucfirst($descriptionContent) === $descriptionContent) {
            return;
        }

        $fixUcFirst = $this->file->addFixableError(
            AbstractDocSniff::MESSAGE_DESCRIPTION_UC_FIRST,
            $descriptionStartPtr,
            AbstractDocSniff::CODE_DESCRIPTION_UC_FIRST
        );

        if ($fixUcFirst) {
            $this->fixDescriptionUcFirst($descriptionStartPtr);
        }
    }

    /**
     * Checks the line length of each line of the comment description.
     *
     * @param int $descriptionStartPtr Pointer to the start of the description.
     * @param int $descriptionEndPtr Pointer to the end of the description.
     *
     * @return void
     */
    private function checkCommentDescriptionLineLength(int $descriptionStartPtr, int $descriptionEndPtr): void
    {
        $diffTokens = array_slice(
            $this->tokens,
            $descriptionStartPtr,
            $descriptionEndPtr - $descriptionStartPtr + 2,
            true
        );

        foreach ($diffTokens as $diffToken) {
            if ($diffToken['type'] !== 'T_DOC_COMMENT_WHITESPACE') {
                continue;
            }

            if ($diffToken['content'] !== $this->file->getEolChar()) {
                continue;
            }

            if ($diffToken['column'] > AbstractDocSniff::MAX_LINE_LENGTH) {
                $this->file->addErrorOnLine(
                    AbstractDocSniff::MESSAGE_DESCRIPTION_TOO_LONG,
                    $diffToken['line'],
                    AbstractDocSniff::CODE_DESCRIPTION_TOO_LONG
                );
            }
        }
    }

    /**
     * Returns pointer to the end of the description.
     *
     * @return int Pointer to the end of the description or false
     */
    private function getCommentDescriptionEndPointer(): int

    {
        $descriptionStartPtr = $this->getCommentDescriptionStartPointer();

        $commentStartToken = $this->docHelper->getCommentStartToken();
        $commentEndPtr = $this->docHelper->getCommentEndPointer();

        //If no tags found, possible end of search is the starting tag of the doc comment.
        if (count($commentStartToken['comment_tags']) === 0) {
            return $this->file->findPrevious(
                [T_DOC_COMMENT_STRING],
                $commentEndPtr - 1,
                $descriptionStartPtr
            );
        }

        //else its the pointer of the first comment tag found.
        $firstTagPtr = array_shift($commentStartToken['comment_tags']);

        return $this->file->findPrevious(
            [T_DOC_COMMENT_STRING],
            $firstTagPtr - 1,
            $descriptionStartPtr
        );
    }

    /**
     * Returns pointer to the start of the long description or false if not found.
     *
     * @return int Pointer to the start of the description or -1
     */
    private function getCommentDescriptionStartPointer(): int

    {
        $commentStartToken = $this->docHelper->getCommentStartToken();
        $commentEndPtr = $this->docHelper->getCommentEndPointer();

        $summaryPtr = $this->summaryHelper->getCommentSummaryPointer();

        //If no tags the possible end of search is the closing tag of the doc comment.
        if (count($commentStartToken['comment_tags']) === 0) {
            return $this->file->findNext(
                [T_DOC_COMMENT_STRING],
                $summaryPtr + 1,
                $commentEndPtr
            );
        }

        //else its the pointer of the first comment tag found.
        $firstTagPtr = array_shift($commentStartToken['comment_tags']);

        return $this->file->findNext(
            [T_DOC_COMMENT_STRING],
            $summaryPtr + 1,
            $firstTagPtr - 1
        );
    }

    /**
     * Adds error when description is not found.
     *
     * @param int $summaryPtr Pointer to summary token.
     *
     * @return void
     */
    private function addDescriptionNotFoundError(int $summaryPtr): void
    {
        if ($this->descriptionRequired) {
            $this->file->addError(
                AbstractDocSniff::MESSAGE_DESCRIPTION_NOT_FOUND,
                $summaryPtr,
                AbstractDocSniff::CODE_DESCRIPTION_NOT_FOUND
            );
        }
    }

    /**
     * Fixes no line after description.
     *
     * @return void
     */
    private function fixNoLineAfterDescription(): void

    {
        $descEndPtr = $this->getCommentDescriptionEndPointer();
        $descEndToken = $this->tokens[$descEndPtr];

        $this->file->getFixer()->beginChangeset();

        $this->file->getFixer()->addContent(
            $descEndPtr,
            $this->file->getEolChar() . str_repeat('    ', $descEndToken['level']) . ' *'
        );

        $this->file->getFixer()->endChangeset();
    }

    /**
     * Fixes much lines after description.
     *
     * @param int $startLine Line to start removing
     * @param int $endLine Line to end removing
     *
     * @return void
     */
    private function fixMuchLinesAfterDescription(int $startLine, int $endLine): void
    {
        $this->file->getFixer()->beginChangeset();

        $this->file->getFixer()->removeLines($startLine, $endLine);

        $this->file->getFixer()->endChangeset();
    }

    /**
     * Fixes the description uc first.
     *
     * @param int $descriptionStartPtr Pointer to the description start
     *
     * @return void
     */
    private function fixDescriptionUcFirst(int $descriptionStartPtr): void

    {
        $descStartToken = $this->tokens[$descriptionStartPtr];

        $this->file->getFixer()->beginChangeset();

        $this->file->getFixer()->replaceToken(
            $descriptionStartPtr,
            ucfirst($descStartToken['content'])
        );

        $this->file->getFixer()->endChangeset();
    }
}


1			<?php
2
3			declare(strict_types=1);
4
5			namespace BestIt\CodeSniffer\Helper;
6
7			use BestIt\CodeSniffer\File;
8			use BestIt\Sniffs\Commenting\AbstractDocSniff;
9
10			/**
11			* Class DocDescriptionHelper
12			*
13			* @package BestIt\Helper
14			* @author Nick Lubisch <[email protected]>
15			*/
16			class DocDescriptionHelper
17			{
18			/**
19			* The php code sniffer file.
20			*
21			* @var File
22			*/
23			private $file;
24
25			/**
26			* The doc comment helper.
27			*
28			* @var DocHelper
29			*/
30			private $docHelper;
31
32			/**
33			* The token stack of the cs file.
34			*
35			* @var array
36			*/
37			private $tokens;
38
39			/**
40			* The doc comment summary helper.
41			*
42			* @var DocSummaryHelper
43			*/
44			private $summaryHelper;
45
46			/**
47			* Indicator if a description is required.
48			*
49			* @var bool
50			*/
51			private $descriptionRequired;
52
53			/**
54			* DocSummaryHelper constructor.
55			*
56			* @param File $file The php cs file
57			* @param DocHelper $docHelper The doc comment helper
58			* @param DocSummaryHelper $summaryHelper The doc comment summary helper
59			*/
60	121		public function __construct(File $file, DocHelper $docHelper, DocSummaryHelper $summaryHelper)
61			{
62	121		$this->file = $file;
63	121		$this->tokens = $file->getTokens();
64	121		$this->docHelper = $docHelper;
65	121		$this->summaryHelper = $summaryHelper;
66	121		}
67
68			/**
69			* Checks for comment description.
70			*
71			* @param bool $descriptionRequired Indicator if the description is required.
72			*
73			* @return void
74			*/
75	113		public function checkCommentDescription(bool $descriptionRequired): void
76			{
77	113		$this->descriptionRequired = $descriptionRequired;
78
79	113		$commentStartToken = $this->docHelper->getCommentStartToken();
80	113		$commentEndToken = $this->docHelper->getCommentEndToken();
81
82	113		$summaryPtr = $this->summaryHelper->getCommentSummaryPointer();
83
84	113		if ($summaryPtr === -1) {
85	4		return;
86			}
87
88	109		$hasTags = count($commentStartToken['comment_tags']) > 0;
89
90	109		$descriptionStartPtr = $this->getCommentDescriptionStartPointer();
91
92	109		if ($descriptionStartPtr === -1) {
93	24		$this->addDescriptionNotFoundError($summaryPtr);
94
95	24		return;
96			}
97
98	86		$descriptionEndPtr = $this->getCommentDescriptionEndPointer();
99	86		$descEndToken = $this->tokens[$descriptionEndPtr];
100
101	86		$this->checkCommentDescriptionUcFirst($descriptionStartPtr);
102	86		$this->checkCommentDescriptionLineLength($descriptionStartPtr, $descriptionEndPtr);
103
104			//Fix no or too much lines after description.
105	86		$toLine = $commentEndToken['line'];
106	86		$expectedLines = 0;
107
108	86		if ($hasTags) {
109	77		$firstTagPtr = array_shift($commentStartToken['comment_tags']);
110	77		$firstTagToken = $this->tokens[$firstTagPtr];
111	77		$toLine = $firstTagToken['line'];
112
113	77		$expectedLines = 1;
114			}
115
116	86		$diffLines = $toLine - $descEndToken['line'] - 1;
117
118	86		if ($diffLines === $expectedLines) {
119	75		return;
120			}
121
122	24		if ($diffLines < $expectedLines && $hasTags) {
123	12		$fixNoLine = $this->file->addFixableError(
124	12		AbstractDocSniff::MESSAGE_NO_LINE_AFTER_DESCRIPTION,
125	12		$descriptionEndPtr,
126	12		AbstractDocSniff::CODE_NO_LINE_AFTER_DESCRIPTION
127			);
128
129	12		if ($fixNoLine) {
130	8		$this->fixNoLineAfterDescription();
131			}
132
133	12		return;
134			}
135
136	16		$fixMuchLines = $this->file->addFixableError(
137	16		AbstractDocSniff::MESSAGE_MUCH_LINES_AFTER_DESCRIPTION,
138	16		$descriptionEndPtr,
139	16		AbstractDocSniff::CODE_MUCH_LINES_AFTER_DESCRIPTION
140			);
141
142	16		if ($fixMuchLines) {
143	8		$this->fixMuchLinesAfterDescription($descEndToken['line'] + 1, $toLine - 1);
144			}
145	16		}
146
147			/**
148			* Checks if the description starts with a capital letter.
149			*
150			* @param int $descriptionStartPtr Pointer to the start of the description.
151			*
152			* @return void
153			*/
154	86		private function checkCommentDescriptionUcFirst(int $descriptionStartPtr): void
155			{
156	86		$descStartToken = $this->tokens[$descriptionStartPtr];
157
158	86		$descriptionContent = $descStartToken['content'];
159
160	86		if (ucfirst($descriptionContent) === $descriptionContent) {
161	82		return;
162			}
163
164	8		$fixUcFirst = $this->file->addFixableError(
165	8		AbstractDocSniff::MESSAGE_DESCRIPTION_UC_FIRST,
166	8		$descriptionStartPtr,
167	8		AbstractDocSniff::CODE_DESCRIPTION_UC_FIRST
168			);
169
170	8		if ($fixUcFirst) {
171	4		$this->fixDescriptionUcFirst($descriptionStartPtr);
172			}
173	8		}
174
175			/**
176			* Checks the line length of each line of the comment description.
177			*
178			* @param int $descriptionStartPtr Pointer to the start of the description.
179			* @param int $descriptionEndPtr Pointer to the end of the description.
180			*
181			* @return void
182			*/
183	86		private function checkCommentDescriptionLineLength(int $descriptionStartPtr, int $descriptionEndPtr): void
184			{
185	86		$diffTokens = array_slice(
186	86		$this->tokens,
187	86		$descriptionStartPtr,
188	86		$descriptionEndPtr - $descriptionStartPtr + 2,
189	86		true
190			);
191
192	86		foreach ($diffTokens as $diffToken) {
193	86		if ($diffToken['type'] !== 'T_DOC_COMMENT_WHITESPACE') {
194	86		continue;
195			}
196
197	86		if ($diffToken['content'] !== $this->file->getEolChar()) {
198	86		continue;
199			}
200
201	86		if ($diffToken['column'] > AbstractDocSniff::MAX_LINE_LENGTH) {
202	4		$this->file->addErrorOnLine(
203	4		AbstractDocSniff::MESSAGE_DESCRIPTION_TOO_LONG,
204	4		$diffToken['line'],
205	4		AbstractDocSniff::CODE_DESCRIPTION_TOO_LONG
206			);
207			}
208			}
209	86		}
210
211			/**
212			* Returns pointer to the end of the description.
213			*
214			* @return int Pointer to the end of the description or false
215			*/
216	86	View Code Duplication	private function getCommentDescriptionEndPointer(): int
			0 ignored issues – show Duplication introduced 2017-08-01 05:36 UTC by Report Bug Copy Issue Report This method seems to be duplicated in your project. Duplicated code is one of the most pungent code smells. If you need to duplicate the same code in three or more different places, we strongly encourage you to look into extracting the code into a single class or operation. You can also find more detailed suggestions in the “Code” section of your repository. Loading history...
217			{
218	86		$descriptionStartPtr = $this->getCommentDescriptionStartPointer();
219
220	86		$commentStartToken = $this->docHelper->getCommentStartToken();
221	86		$commentEndPtr = $this->docHelper->getCommentEndPointer();
222
223			//If no tags found, possible end of search is the starting tag of the doc comment.
224	86		if (count($commentStartToken['comment_tags']) === 0) {
225	11		return $this->file->findPrevious(
226	11		[T_DOC_COMMENT_STRING],
227	11		$commentEndPtr - 1,
228	11		$descriptionStartPtr
229			);
230			}
231
232			//else its the pointer of the first comment tag found.
233	77		$firstTagPtr = array_shift($commentStartToken['comment_tags']);
234
235	77		return $this->file->findPrevious(
236	77		[T_DOC_COMMENT_STRING],
237	77		$firstTagPtr - 1,
238	77		$descriptionStartPtr
239			);
240			}
241
242			/**
243			* Returns pointer to the start of the long description or false if not found.
244			*
245			* @return int Pointer to the start of the description or -1
246			*/
247	109	View Code Duplication	private function getCommentDescriptionStartPointer(): int
			0 ignored issues – show Duplication introduced 2017-08-01 05:36 UTC by Report Bug Copy Issue Report This method seems to be duplicated in your project. Duplicated code is one of the most pungent code smells. If you need to duplicate the same code in three or more different places, we strongly encourage you to look into extracting the code into a single class or operation. You can also find more detailed suggestions in the “Code” section of your repository. Loading history...
248			{
249	109		$commentStartToken = $this->docHelper->getCommentStartToken();
250	109		$commentEndPtr = $this->docHelper->getCommentEndPointer();
251
252	109		$summaryPtr = $this->summaryHelper->getCommentSummaryPointer();
253
254			//If no tags the possible end of search is the closing tag of the doc comment.
255	109		if (count($commentStartToken['comment_tags']) === 0) {
256	12		return $this->file->findNext(
257	12		[T_DOC_COMMENT_STRING],
258	12		$summaryPtr + 1,
259	12		$commentEndPtr
260			);
261			}
262
263			//else its the pointer of the first comment tag found.
264	99		$firstTagPtr = array_shift($commentStartToken['comment_tags']);
265
266	99		return $this->file->findNext(
267	99		[T_DOC_COMMENT_STRING],
268	99		$summaryPtr + 1,
269	99		$firstTagPtr - 1
270			);
271			}
272
273			/**
274			* Adds error when description is not found.
275			*
276			* @param int $summaryPtr Pointer to summary token.
277			*
278			* @return void
279			*/
280	24		private function addDescriptionNotFoundError(int $summaryPtr): void
281			{
282	24		if ($this->descriptionRequired) {
283	4		$this->file->addError(
284	4		AbstractDocSniff::MESSAGE_DESCRIPTION_NOT_FOUND,
285	4		$summaryPtr,
286	4		AbstractDocSniff::CODE_DESCRIPTION_NOT_FOUND
287			);
288			}
289	24		}
290
291			/**
292			* Fixes no line after description.
293			*
294			* @return void
295			*/
296	8	View Code Duplication	private function fixNoLineAfterDescription(): void
			0 ignored issues – show Duplication introduced 2017-08-01 05:36 UTC by Report Bug Copy Issue Report This method seems to be duplicated in your project. Duplicated code is one of the most pungent code smells. If you need to duplicate the same code in three or more different places, we strongly encourage you to look into extracting the code into a single class or operation. You can also find more detailed suggestions in the “Code” section of your repository. Loading history...
297			{
298	8		$descEndPtr = $this->getCommentDescriptionEndPointer();
299	8		$descEndToken = $this->tokens[$descEndPtr];
300
301	8		$this->file->getFixer()->beginChangeset();
302
303	8		$this->file->getFixer()->addContent(
304	8		$descEndPtr,
305	8		$this->file->getEolChar() . str_repeat(' ', $descEndToken['level']) . ' *'
306			);
307
308	8		$this->file->getFixer()->endChangeset();
309	8		}
310
311			/**
312			* Fixes much lines after description.
313			*
314			* @param int $startLine Line to start removing
315			* @param int $endLine Line to end removing
316			*
317			* @return void
318			*/
319	8		private function fixMuchLinesAfterDescription(int $startLine, int $endLine): void
320			{
321	8		$this->file->getFixer()->beginChangeset();
322
323	8		$this->file->getFixer()->removeLines($startLine, $endLine);
324
325	8		$this->file->getFixer()->endChangeset();
326	8		}
327
328			/**
329			* Fixes the description uc first.
330			*
331			* @param int $descriptionStartPtr Pointer to the description start
332			*
333			* @return void
334			*/
335	4	View Code Duplication	private function fixDescriptionUcFirst(int $descriptionStartPtr): void
			0 ignored issues – show Duplication introduced 2017-08-01 05:36 UTC by Report Bug Copy Issue Report This method seems to be duplicated in your project. Duplicated code is one of the most pungent code smells. If you need to duplicate the same code in three or more different places, we strongly encourage you to look into extracting the code into a single class or operation. You can also find more detailed suggestions in the “Code” section of your repository. Loading history...
336			{
337	4		$descStartToken = $this->tokens[$descriptionStartPtr];
338
339	4		$this->file->getFixer()->beginChangeset();
340
341	4		$this->file->getFixer()->replaceToken(
342	4		$descriptionStartPtr,
343	4		ucfirst($descStartToken['content'])
344			);
345
346	4		$this->file->getFixer()->endChangeset();
347	4		}
348			}
349

bestit / PHP_CodeSniffer

Pull Request — master (#19)

DocDescriptionHelper::fixDescriptionUcFirst() A

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like