From 13bdf4d7df6fbd5a3a5cba9b0e260c341b6faefd Mon Sep 17 00:00:00 2001 From: jrfnl Date: Wed, 6 Nov 2024 01:30:44 +0100 Subject: [PATCH] Generator::getTitle(): fall back to file name if title is missing When the documentation `title` attribute is missing, a title would still be included in the docs, but not contain any (useful) information. Fixed now by falling back to the XML document file name and splitting the name into words. Includes tests. --- src/Generators/Generator.php | 17 +++- ...dOutputDocumentationTitlePCREFallback.html | 79 +++++++++++++++++++ ...tedOutputDocumentationTitlePCREFallback.md | 9 +++ ...edOutputDocumentationTitlePCREFallback.txt | 9 +++ ...dOutputInvalidDocumentationTitleEmpty.html | 4 +- ...tedOutputInvalidDocumentationTitleEmpty.md | 2 +- ...edOutputInvalidDocumentationTitleEmpty.txt | 6 +- ...utputInvalidDocumentationTitleMissing.html | 4 +- ...dOutputInvalidDocumentationTitleMissing.md | 2 +- ...OutputInvalidDocumentationTitleMissing.txt | 6 +- ...DocumentationTitlePCREFallbackStandard.xml | 9 +++ .../DocumentationTitlePCREFallbackSniff.php | 12 +++ tests/Core/Generators/GeneratorTest.php | 33 ++++++++ tests/Core/Generators/HTMLTest.php | 4 + tests/Core/Generators/MarkdownTest.php | 4 + tests/Core/Generators/TextTest.php | 4 + 16 files changed, 191 insertions(+), 13 deletions(-) create mode 100644 tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html create mode 100644 tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md create mode 100644 tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt create mode 100644 tests/Core/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitlePCREFallbackStandard.xml create mode 100644 tests/Core/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitlePCREFallbackSniff.php diff --git a/src/Generators/Generator.php b/src/Generators/Generator.php index 873ac3f3fa..9878cc4573 100644 --- a/src/Generators/Generator.php +++ b/src/Generators/Generator.php @@ -83,7 +83,22 @@ public function __construct(Ruleset $ruleset) */ protected function getTitle(DOMNode $doc) { - return $doc->getAttribute('title'); + $title = $doc->getAttribute('title'); + + if (empty($title) === true) { + // Fall back to the sniff name if no title was supplied. + $fileName = $doc->ownerDocument->documentURI; + $lastSlash = strrpos($fileName, '/'); + if (is_int($lastSlash) === true) { + // Get the sniff name without "Standard.xml". + $title = substr($fileName, ($lastSlash + 1), -12); + + // Split the sniff name to individual words. + $title = preg_replace('`[-._]|(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])`', '$1 $2', $title); + } + } + + return $title; }//end getTitle() diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html new file mode 100644 index 0000000000..80cf616fde --- /dev/null +++ b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html @@ -0,0 +1,79 @@ + + + GeneratorTest Coding Standards + + + +

GeneratorTest Coding Standards

+ +

Documentation Title PCRE Fallback

+

Testing the document title can get determined from the sniff name if missing.

+

This file name contains an acronym on purpose to test the word splitting.

+
Documentation generated on #REDACTED# by PHP_CodeSniffer #VERSION#
+ + diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md new file mode 100644 index 0000000000..844f4fbb40 --- /dev/null +++ b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md @@ -0,0 +1,9 @@ +# GeneratorTest Coding Standard + +## Documentation Title PCRE Fallback + +Testing the document title can get determined from the sniff name if missing. + +This file name contains an acronym on purpose to test the word splitting. + +Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer) diff --git a/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt new file mode 100644 index 0000000000..342cdfda53 --- /dev/null +++ b/tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt @@ -0,0 +1,9 @@ + +-------------------------------------------------------------------- +| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE PCRE FALLBACK | +-------------------------------------------------------------------- + +Testing the document title can get determined from the sniff name if missing. + +This file name contains an acronym on purpose to test the word splitting. + diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.html b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.html index c3c92a8a37..440153b72e 100644 --- a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.html +++ b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.html @@ -70,8 +70,8 @@

GeneratorTest Coding Standards

- -

+ +

Documentation Title Empty

The above "documentation" element has an empty title attribute.

diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.md b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.md index d36609c0f6..db8b2e40e5 100644 --- a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.md +++ b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.md @@ -1,6 +1,6 @@ # GeneratorTest Coding Standard -## +## Documentation Title Empty The above "documentation" element has an empty title attribute.
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.txt b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.txt index 8fb0182be5..85fe3779b4 100644 --- a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.txt +++ b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.txt @@ -1,7 +1,7 @@ ------------------------------------ -| GENERATORTEST CODING STANDARD: | ------------------------------------ +------------------------------------------------------------ +| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE EMPTY | +------------------------------------------------------------ The above "documentation" element has an empty title attribute. diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.html b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.html index d0af2bea8b..5cb16fbd2a 100644 --- a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.html +++ b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.html @@ -70,8 +70,8 @@

GeneratorTest Coding Standards

- -

+ +

Documentation Title Missing

The above "documentation" element is missing the title attribute.

 diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.md b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.md index 5dc91a6479..bd9ebfd145 100644 --- a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.md +++ b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.md @@ -1,6 +1,6 @@ # GeneratorTest Coding Standard -## +## Documentation Title Missing The above "documentation" element is missing the title attribute.
diff --git a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.txt b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.txt index 85ef693575..d495203813 100644 --- a/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.txt +++ b/tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.txt @@ -1,7 +1,7 @@ ------------------------------------ -| GENERATORTEST CODING STANDARD: | ------------------------------------ +-------------------------------------------------------------- +| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE MISSING | +-------------------------------------------------------------- The above "documentation" element is missing the title attribute. diff --git a/tests/Core/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitlePCREFallbackStandard.xml b/tests/Core/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitlePCREFallbackStandard.xml new file mode 100644 index 0000000000..1aa3849bd1 --- /dev/null +++ b/tests/Core/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitlePCREFallbackStandard.xml @@ -0,0 +1,9 @@ + + + + + diff --git a/tests/Core/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitlePCREFallbackSniff.php b/tests/Core/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitlePCREFallbackSniff.php new file mode 100644 index 0000000000..fd17bdf7b3 --- /dev/null +++ b/tests/Core/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitlePCREFallbackSniff.php @@ -0,0 +1,12 @@ +` title is missing, it will fallback to the file name + * and split the CamelCaps name correctly. + * + * @return void + */ + public function testGetTitleFallbackToFilename() + { + // Set up the ruleset. + $standard = __DIR__.'/AllValidDocsTest.xml'; + $sniffs = 'StandardWithDocs.Content.DocumentationTitlePCREFallback'; + $config = new ConfigDouble(["--standard=$standard", "--sniffs=$sniffs"]); + $ruleset = new Ruleset($config); + + // In tests, the `--sniffs` setting doesn't work out of the box. + $sniffParts = explode('.', $sniffs); + $sniffFile = __DIR__.DIRECTORY_SEPARATOR.'Fixtures'.DIRECTORY_SEPARATOR.$sniffParts[0].DIRECTORY_SEPARATOR; + $sniffFile .= 'Sniffs'.DIRECTORY_SEPARATOR.$sniffParts[1].DIRECTORY_SEPARATOR.$sniffParts[2].'Sniff.php'; + + $sniffParts = array_map('strtolower', $sniffParts); + $sniffName = $sniffParts[0].'\sniffs\\'.$sniffParts[1].'\\'.$sniffParts[2].'sniff'; + $restrictions = [$sniffName => true]; + $ruleset->registerSniffs([$sniffFile], $restrictions, []); + + // Make the test OS independent. + $this->expectOutputString('Documentation Title PCRE Fallback'.PHP_EOL); + + $generator = new MockGenerator($ruleset); + $generator->generate(); + + }//end testGetTitleFallbackToFilename() + + /** * Test that the documentation for each standard passed on the command-line is shown separately. * diff --git a/tests/Core/Generators/HTMLTest.php b/tests/Core/Generators/HTMLTest.php index ebd61a6f28..82f8d7faeb 100644 --- a/tests/Core/Generators/HTMLTest.php +++ b/tests/Core/Generators/HTMLTest.php @@ -133,6 +133,10 @@ public static function dataDocSpecifics() 'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength', 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.html', ], + 'Documentation title: fallback to file name' => [ + 'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback', + 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html', + ], 'Standard Element: blank line handling' => [ 'sniffs' => 'StandardWithDocs.Content.StandardBlankLines', 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.html', diff --git a/tests/Core/Generators/MarkdownTest.php b/tests/Core/Generators/MarkdownTest.php index 1bcddbebcc..6bc2c4fba2 100644 --- a/tests/Core/Generators/MarkdownTest.php +++ b/tests/Core/Generators/MarkdownTest.php @@ -133,6 +133,10 @@ public static function dataDocSpecifics() 'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength', 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.md', ], + 'Documentation title: fallback to file name' => [ + 'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback', + 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md', + ], 'Standard Element: blank line handling' => [ 'sniffs' => 'StandardWithDocs.Content.StandardBlankLines', 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.md', diff --git a/tests/Core/Generators/TextTest.php b/tests/Core/Generators/TextTest.php index 33d6c7e1db..90bb7bf89c 100644 --- a/tests/Core/Generators/TextTest.php +++ b/tests/Core/Generators/TextTest.php @@ -133,6 +133,10 @@ public static function dataDocSpecifics() 'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength', 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.txt', ], + 'Documentation title: fallback to file name' => [ + 'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback', + 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt', + ], 'Standard Element: blank line handling' => [ 'sniffs' => 'StandardWithDocs.Content.StandardBlankLines', 'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.txt',