Skip to content

Commit 13bdf4d

Browse files
jrfnljrfnl
committed
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.
1 parent a7d77cf commit 13bdf4d

16 files changed

+191
-13
lines changed

‎src/Generators/Generator.php

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,22 @@ public function __construct(Ruleset $ruleset)
8383
*/
8484
protected function getTitle(DOMNode $doc)
8585
{
86-
return $doc->getAttribute('title');
86+
$title = $doc->getAttribute('title');
87+
88+
if (empty($title) === true) {
89+
// Fall back to the sniff name if no title was supplied.
90+
$fileName = $doc->ownerDocument->documentURI;
91+
$lastSlash = strrpos($fileName, '/');
92+
if (is_int($lastSlash) === true) {
93+
// Get the sniff name without "Standard.xml".
94+
$title = substr($fileName, ($lastSlash + 1), -12);
95+
96+
// Split the sniff name to individual words.
97+
$title = preg_replace('`[-._]|(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])`', '$1 $2', $title);
98+
}
99+
}
100+
101+
return $title;
87102

88103
}//end getTitle()
89104

‎tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
<html>
2+
<head>
3+
<title>GeneratorTest Coding Standards</title>
4+
<style>
5+
body {
6+
background-color: #FFFFFF;
7+
font-size: 14px;
8+
font-family: Arial, Helvetica, sans-serif;
9+
color: #000000;
10+
}
11+
12+
h1 {
13+
color: #666666;
14+
font-size: 20px;
15+
font-weight: bold;
16+
margin-top: 0px;
17+
background-color: #E6E7E8;
18+
padding: 20px;
19+
border: 1px solid #BBBBBB;
20+
}
21+
22+
h2 {
23+
color: #00A5E3;
24+
font-size: 16px;
25+
font-weight: normal;
26+
margin-top: 50px;
27+
}
28+
29+
.code-comparison {
30+
width: 100%;
31+
}
32+
33+
.code-comparison td {
34+
border: 1px solid #CCCCCC;
35+
}
36+
37+
.code-comparison-title, .code-comparison-code {
38+
font-family: Arial, Helvetica, sans-serif;
39+
font-size: 12px;
40+
color: #000000;
41+
vertical-align: top;
42+
padding: 4px;
43+
width: 50%;
44+
background-color: #F1F1F1;
45+
line-height: 15px;
46+
}
47+
48+
.code-comparison-code {
49+
font-family: Courier;
50+
background-color: #F9F9F9;
51+
}
52+
53+
.code-comparison-highlight {
54+
background-color: #DDF1F7;
55+
border: 1px solid #00A5E3;
56+
line-height: 15px;
57+
}
58+
59+
.tag-line {
60+
text-align: center;
61+
width: 100%;
62+
margin-top: 30px;
63+
font-size: 12px;
64+
}
65+
66+
.tag-line a {
67+
color: #000000;
68+
}
69+
</style>
70+
</head>
71+
<body>
72+
<h1>GeneratorTest Coding Standards</h1>
73+
<a name="Documentation-Title-PCRE-Fallback" />
74+
<h2>Documentation Title PCRE Fallback</h2>
75+
<p class="text">Testing the document title can get determined from the sniff name if missing.</p>
76+
<p class="text">This file name contains an acronym on purpose to test the word splitting.</p>
77+
<div class="tag-line">Documentation generated on #REDACTED# by <a href="https://github.com/PHPCSStandards/PHP_CodeSniffer">PHP_CodeSniffer #VERSION#</a></div>
78+
</body>
79+
</html>

‎tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# GeneratorTest Coding Standard
2+
3+
## Documentation Title PCRE Fallback
4+
5+
Testing the document title can get determined from the sniff name if missing.
6+
7+
This file name contains an acronym on purpose to test the word splitting.
8+
9+
Documentation generated on *REDACTED* by [PHP_CodeSniffer *VERSION*](https://github.com/PHPCSStandards/PHP_CodeSniffer)

‎tests/Core/Generators/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
2+
--------------------------------------------------------------------
3+
| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE PCRE FALLBACK |
4+
--------------------------------------------------------------------
5+
6+
Testing the document title can get determined from the sniff name if missing.
7+
8+
This file name contains an acronym on purpose to test the word splitting.
9+

‎tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,8 @@
7070
</head>
7171
<body>
7272
<h1>GeneratorTest Coding Standards</h1>
73-
<a name="" />
74-
<h2></h2>
73+
<a name="Documentation-Title-Empty" />
74+
<h2>Documentation Title Empty</h2>
7575
<p class="text">The above &quot;documentation&quot; element has an empty title attribute.</p>
7676
<table class="code-comparison">
7777
<tr>

‎tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# GeneratorTest Coding Standard
22

3-
##
3+
## Documentation Title Empty
44

55
The above &quot;documentation&quot; element has an empty title attribute.
66
<table>

‎tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleEmpty.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11

2-
-----------------------------------
3-
| GENERATORTEST CODING STANDARD: |
4-
-----------------------------------
2+
------------------------------------------------------------
3+
| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE EMPTY |
4+
------------------------------------------------------------
55

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

‎tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,8 @@
7070
</head>
7171
<body>
7272
<h1>GeneratorTest Coding Standards</h1>
73-
<a name="" />
74-
<h2></h2>
73+
<a name="Documentation-Title-Missing" />
74+
<h2>Documentation Title Missing</h2>
7575
<p class="text">The above &quot;documentation&quot; element is missing the title attribute.</p>
7676
<table class="code-comparison">
7777
<tr>

‎tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# GeneratorTest Coding Standard
22

3-
##
3+
## Documentation Title Missing
44

55
The above &quot;documentation&quot; element is missing the title attribute.
66
<table>

‎tests/Core/Generators/Expectations/ExpectedOutputInvalidDocumentationTitleMissing.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11

2-
-----------------------------------
3-
| GENERATORTEST CODING STANDARD: |
4-
-----------------------------------
2+
--------------------------------------------------------------
3+
| GENERATORTEST CODING STANDARD: DOCUMENTATION TITLE MISSING |
4+
--------------------------------------------------------------
55

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

‎tests/Core/Generators/Fixtures/StandardWithDocs/Docs/Content/DocumentationTitlePCREFallbackStandard.xml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<documentation>
2+
<standard>
3+
<![CDATA[
4+
Testing the document title can get determined from the sniff name if missing.
5+
6+
This file name contains an acronym on purpose to test the word splitting.
7+
]]>
8+
</standard>
9+
</documentation>

‎tests/Core/Generators/Fixtures/StandardWithDocs/Sniffs/Content/DocumentationTitlePCREFallbackSniff.php

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<?php
2+
/**
3+
* Test fixture.
4+
*
5+
* @see \PHP_CodeSniffer\Tests\Core\Generators\GeneratorTest
6+
*/
7+
8+
namespace Fixtures\StandardWithDocs\Sniffs\Content;
9+
10+
use Fixtures\StandardWithDocs\Sniffs\DummySniff;
11+
12+
final class DocumentationTitlePCREFallbackSniff extends DummySniff {}

‎tests/Core/Generators/GeneratorTest.php

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,39 @@ public static function dataGeneratingDocs()
192192
}//end dataGeneratingDocs()
193193

194194

195+
/**
196+
* Verify that if the `<documentation>` title is missing, it will fallback to the file name
197+
* and split the CamelCaps name correctly.
198+
*
199+
* @return void
200+
*/
201+
public function testGetTitleFallbackToFilename()
202+
{
203+
// Set up the ruleset.
204+
$standard = __DIR__.'/AllValidDocsTest.xml';
205+
$sniffs = 'StandardWithDocs.Content.DocumentationTitlePCREFallback';
206+
$config = new ConfigDouble(["--standard=$standard", "--sniffs=$sniffs"]);
207+
$ruleset = new Ruleset($config);
208+
209+
// In tests, the `--sniffs` setting doesn't work out of the box.
210+
$sniffParts = explode('.', $sniffs);
211+
$sniffFile = __DIR__.DIRECTORY_SEPARATOR.'Fixtures'.DIRECTORY_SEPARATOR.$sniffParts[0].DIRECTORY_SEPARATOR;
212+
$sniffFile .= 'Sniffs'.DIRECTORY_SEPARATOR.$sniffParts[1].DIRECTORY_SEPARATOR.$sniffParts[2].'Sniff.php';
213+
214+
$sniffParts = array_map('strtolower', $sniffParts);
215+
$sniffName = $sniffParts[0].'\sniffs\\'.$sniffParts[1].'\\'.$sniffParts[2].'sniff';
216+
$restrictions = [$sniffName => true];
217+
$ruleset->registerSniffs([$sniffFile], $restrictions, []);
218+
219+
// Make the test OS independent.
220+
$this->expectOutputString('Documentation Title PCRE Fallback'.PHP_EOL);
221+
222+
$generator = new MockGenerator($ruleset);
223+
$generator->generate();
224+
225+
}//end testGetTitleFallbackToFilename()
226+
227+
195228
/**
196229
* Test that the documentation for each standard passed on the command-line is shown separately.
197230
*

‎tests/Core/Generators/HTMLTest.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,10 @@ public static function dataDocSpecifics()
133133
'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength',
134134
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.html',
135135
],
136+
'Documentation title: fallback to file name' => [
137+
'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback',
138+
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.html',
139+
],
136140
'Standard Element: blank line handling' => [
137141
'sniffs' => 'StandardWithDocs.Content.StandardBlankLines',
138142
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.html',

‎tests/Core/Generators/MarkdownTest.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,10 @@ public static function dataDocSpecifics()
133133
'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength',
134134
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.md',
135135
],
136+
'Documentation title: fallback to file name' => [
137+
'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback',
138+
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.md',
139+
],
136140
'Standard Element: blank line handling' => [
137141
'sniffs' => 'StandardWithDocs.Content.StandardBlankLines',
138142
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.md',

‎tests/Core/Generators/TextTest.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,10 @@ public static function dataDocSpecifics()
133133
'sniffs' => 'StandardWithDocs.Content.DocumentationTitleLength',
134134
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitleLength.txt',
135135
],
136+
'Documentation title: fallback to file name' => [
137+
'sniffs' => 'StandardWithDocs.Content.DocumentationTitlePCREFallback',
138+
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputDocumentationTitlePCREFallback.txt',
139+
],
136140
'Standard Element: blank line handling' => [
137141
'sniffs' => 'StandardWithDocs.Content.StandardBlankLines',
138142
'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputStandardBlankLines.txt',

0 commit comments

Comments
 (0)