forked from moodlehq/moodle-cs
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add sniff to detect missing docblocks
- Loading branch information
1 parent
850bb3c
commit 266ae67
Showing
14 changed files
with
518 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,122 @@ | ||
<?php | ||
|
||
// This file is part of Moodle - https://moodle.org/ | ||
// | ||
// Moodle is free software: you can redistribute it and/or modify | ||
// it under the terms of the GNU General Public License as published by | ||
// the Free Software Foundation, either version 3 of the License, or | ||
// (at your option) any later version. | ||
// | ||
// Moodle is distributed in the hope that it will be useful, | ||
// but WITHOUT ANY WARRANdTY; without even the implied warranty of | ||
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
// GNU General Public License for more details. | ||
// | ||
// You should have received a copy of the GNU General Public License | ||
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Sniffs\Commenting; | ||
|
||
use MoodleHQ\MoodleCS\moodle\Util\Docblocks; | ||
use MoodleHQ\MoodleCS\moodle\Util\Tokens; | ||
use PHP_CodeSniffer\Files\File; | ||
use PHP_CodeSniffer\Sniffs\Sniff; | ||
use PHPCSUtils\Utils\ObjectDeclarations; | ||
|
||
/** | ||
* Checks that all files an classes have appropriate docs. | ||
* | ||
* @copyright 2024 Andrew Lyons <andrew@nicols.co.uk> | ||
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | ||
*/ | ||
class MissingDocblockSniff implements Sniff | ||
{ | ||
/** | ||
* Register for open tag (only process once per file). | ||
*/ | ||
public function register() { | ||
return [ | ||
T_OPEN_TAG, | ||
]; | ||
} | ||
|
||
/** | ||
* Processes php files and perform various checks with file. | ||
* | ||
* @param File $phpcsFile The file being scanned. | ||
* @param int $stackPtr The position in the stack. | ||
*/ | ||
public function process(File $phpcsFile, $stackPtr) { | ||
$tokens = $phpcsFile->getTokens(); | ||
|
||
// Each class, interface, trait, and enum must have a docblock. | ||
// If a file has one class, interface, trait, or enum, the file docblock is optinoal. | ||
// Otherwise, the file docblock is required. | ||
|
||
// First find out how many items there are. | ||
$find = [ | ||
// Classes, enums, interfaces, and traits. | ||
T_CLASS, | ||
T_ENUM, | ||
T_INTERFACE, | ||
T_TRAIT, | ||
|
||
// Functions outside of those. | ||
T_FUNCTION, | ||
]; | ||
|
||
$artefactCount = 0; | ||
$missingDocblocks = []; | ||
|
||
$typePtr = $stackPtr + 1; | ||
while ($typePtr = $phpcsFile->findNext($find, $typePtr + 1)) { | ||
$token = $tokens[$typePtr]; | ||
if ($token['code'] === T_FUNCTION && !empty($token['conditions'])) { | ||
// Skip methods of classes, traits and interfaces. | ||
continue; | ||
} | ||
|
||
$artefactCount++; | ||
|
||
if ($docblock = Docblocks::getDocBlock($phpcsFile, $typePtr)) { | ||
// There should be no empty lines between the artefact and the docblock. | ||
$lastline = $tokens[$docblock['comment_closer']]['line']; | ||
for ($interimPtr = $docblock['comment_closer'] + 1; $interimPtr < $typePtr; $interimPtr++) { | ||
if ($tokens[$interimPtr]['code'] === T_ATTRIBUTE) { | ||
$interimPtr = $tokens[$interimPtr]['attribute_closer']; | ||
$lastline = $tokens[$interimPtr]['line']; | ||
continue; | ||
} | ||
if ($tokens[$interimPtr]['line'] > $lastline) { | ||
$missingDocblocks[] = $typePtr; | ||
break; | ||
} | ||
} | ||
} else { | ||
$missingDocblocks[] = $typePtr; | ||
} | ||
} | ||
|
||
if ($artefactCount !== 1) { | ||
// See if there is a file docblock. | ||
$fileblock = Docblocks::getDocBlock($phpcsFile, $stackPtr); | ||
|
||
if ($fileblock === null) { | ||
$objectName = Tokens::getObjectName($phpcsFile, $stackPtr); | ||
$phpcsFile->addError('Missing docblock for file %s', $stackPtr, 'Missing', [$objectName]); | ||
} | ||
} | ||
|
||
foreach ($missingDocblocks as $typePtr) { | ||
$objectName = Tokens::getObjectName($phpcsFile, $typePtr); | ||
$objectType = Tokens::getObjectType($phpcsFile, $typePtr); | ||
$phpcsFile->addError('Missing docblock for %s %s', $typePtr, 'Missing', [$objectType, $objectName]); | ||
} | ||
|
||
if ($artefactCount === 1) { | ||
// Only one artefact. | ||
// No need for file docblock. | ||
return; | ||
} | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
117 changes: 117 additions & 0 deletions
117
moodle/Tests/Sniffs/Commenting/MissingDocblockSniffTest.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,117 @@ | ||
<?php | ||
|
||
// This file is part of Moodle - https://moodle.org/ | ||
// | ||
// Moodle is free software: you can redistribute it and/or modify | ||
// it under the terms of the GNU General Public License as published by | ||
// the Free Software Foundation, either version 3 of the License, or | ||
// (at your option) any later version. | ||
// | ||
// Moodle is distributed in the hope that it will be useful, | ||
// but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
// GNU General Public License for more details. | ||
// | ||
// You should have received a copy of the GNU General Public License | ||
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\Commenting; | ||
|
||
use MoodleHQ\MoodleCS\moodle\Tests\MoodleCSBaseTestCase; | ||
|
||
/** | ||
* Test the MissingDocblockSniff sniff. | ||
* | ||
* @copyright 2024 onwards Andrew Lyons <andrew@nicols.co.uk> | ||
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | ||
* | ||
* @covers \MoodleHQ\MoodleCS\moodle\Sniffs\Commenting\MissingDocblockSniff | ||
*/ | ||
class MissingDocblockSniffTest extends MoodleCSBaseTestCase | ||
{ | ||
/** | ||
* @dataProvider docblockCorrectnessProvider | ||
*/ | ||
public function testMissingDocblockSnfif( | ||
string $fixture, | ||
array $errors, | ||
array $warnings | ||
): void { | ||
$this->setStandard('moodle'); | ||
$this->setSniff('moodle.Commenting.MissingDocblock'); | ||
$this->setFixture(sprintf("%s/fixtures/%s.php", __DIR__, $fixture)); | ||
$this->setWarnings($warnings); | ||
$this->setErrors($errors); | ||
$this->setComponentMapping([ | ||
'local_codechecker' => dirname(__DIR__), | ||
]); | ||
|
||
$this->verifyCsResults(); | ||
} | ||
|
||
public static function docblockCorrectnessProvider(): array { | ||
return [ | ||
'Multiple artefacts in a file' => [ | ||
'fixture' => 'missing_docblock_multiple_artefacts', | ||
'errors' => [ | ||
1 => 'Missing docblock for file missing_docblock_multiple_artefacts.php', | ||
34 => 'Missing docblock for function missing_docblock_in_function', | ||
38 => 'Missing docblock for class missing_docblock_in_class', | ||
95 => 'Missing docblock for interface missing_docblock_interface', | ||
118 => 'Missing docblock for trait missing_docblock_trait', ], | ||
'warnings' => [], | ||
], | ||
'File level tag, no class' => [ | ||
'fixture' => 'missing_docblock_class_without_docblock', | ||
'errors' => [ | ||
11 => 'Missing docblock for class class_without_docblock', | ||
], | ||
'warnings' => [], | ||
], | ||
'Class only (incorrect whitespace)' => [ | ||
'fixture' => 'missing_docblock_class_only_with_incorrect_whitespace', | ||
'errors' => [ | ||
11 => 'Missing docblock for class class_only_with_incorrect_whitespace', | ||
], | ||
'warnings' => [], | ||
], | ||
'Class only (correct)' => [ | ||
'fixture' => 'missing_docblock_class_only', | ||
'errors' => [], | ||
'warnings' => [], | ||
], | ||
'Class only with attributes (correct)' => [ | ||
'fixture' => 'missing_docblock_class_only_with_attributes', | ||
'errors' => [], | ||
'warnings' => [], | ||
], | ||
'Class only with attributes and incorrect whitespace' => [ | ||
'fixture' => 'missing_docblock_class_only_with_attributes_incorrect_whitespace', | ||
'errors' => [ | ||
13 => 'Missing docblock for class class_only_with_attributes_incorrect_whitespace', | ||
], | ||
'warnings' => [], | ||
], | ||
'Class and file (correct)' => [ | ||
'fixture' => 'missing_docblock_class_and_file', | ||
'errors' => [], | ||
'warnings' => [], | ||
], | ||
'Enum only (correct)' => [ | ||
'fixture' => 'missing_docblock_enum_only', | ||
'errors' => [], | ||
'warnings' => [], | ||
], | ||
'Interface only (correct)' => [ | ||
'fixture' => 'missing_docblock_interface_only', | ||
'errors' => [], | ||
'warnings' => [], | ||
], | ||
'Trait only (correct)' => [ | ||
'fixture' => 'missing_docblock_trait_only', | ||
'errors' => [], | ||
'warnings' => [], | ||
], | ||
]; | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
15 changes: 15 additions & 0 deletions
15
moodle/Tests/Sniffs/Commenting/fixtures/missing_docblock_class_and_file.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
<?php | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit; | ||
|
||
/** | ||
* File level docblock. | ||
*/ | ||
|
||
use example; | ||
|
||
/** | ||
* Class level docblock. | ||
*/ | ||
class class_only { | ||
} |
11 changes: 11 additions & 0 deletions
11
moodle/Tests/Sniffs/Commenting/fixtures/missing_docblock_class_only.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
<?php | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit; | ||
|
||
use example; | ||
|
||
/** | ||
* Class level docblock. | ||
*/ | ||
class class_only { | ||
} |
13 changes: 13 additions & 0 deletions
13
moodle/Tests/Sniffs/Commenting/fixtures/missing_docblock_class_only_with_attributes.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
<?php | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit; | ||
|
||
use example; | ||
|
||
/** | ||
* Class level docblock. | ||
*/ | ||
#[example_attribute] | ||
#[with_multiple_attributes, and_another_attribute] | ||
class class_with_docblock_and_attributes { | ||
} |
14 changes: 14 additions & 0 deletions
14
.../Commenting/fixtures/missing_docblock_class_only_with_attributes_incorrect_whitespace.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,14 @@ | ||
<?php | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit; | ||
|
||
use example; | ||
|
||
/** | ||
* Class level docblock. | ||
*/ | ||
#[example_attribute] | ||
#[with_multiple_attributes, and_another_attribute] | ||
|
||
class class_only_with_attributes_incorrect_whitespace { | ||
} |
12 changes: 12 additions & 0 deletions
12
...ests/Sniffs/Commenting/fixtures/missing_docblock_class_only_with_incorrect_whitespace.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
<?php | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit; | ||
|
||
use example; | ||
|
||
/** | ||
* Class level docblock but incorrect whitespace. | ||
*/ | ||
|
||
class class_only_with_incorrect_whitespace { | ||
} |
12 changes: 12 additions & 0 deletions
12
moodle/Tests/Sniffs/Commenting/fixtures/missing_docblock_class_without_docblock.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
<?php | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit; | ||
|
||
/** | ||
* File level tag | ||
*/ | ||
|
||
use example; | ||
|
||
class class_without_docblock { | ||
} |
11 changes: 11 additions & 0 deletions
11
moodle/Tests/Sniffs/Commenting/fixtures/missing_docblock_enum_only.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
<?php | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit; | ||
|
||
use example; | ||
|
||
/** | ||
* Enum level docblock. | ||
*/ | ||
enum class_only { | ||
} |
11 changes: 11 additions & 0 deletions
11
moodle/Tests/Sniffs/Commenting/fixtures/missing_docblock_interface_only.php
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
<?php | ||
|
||
namespace MoodleHQ\MoodleCS\moodle\Tests\Sniffs\PHPUnit; | ||
|
||
use example; | ||
|
||
/** | ||
* interface level docblock. | ||
*/ | ||
interface interface_only { | ||
} |
Oops, something went wrong.