Skip to content

Commit 48dfde0

Browse files
Anushreebasicsromani
Anushreebasics
authored and
romani
committed
Issue #18809: removed xdocs section markers
1 parent 8ffb662 commit 48dfde0

File tree

10 files changed

+96
-43
lines changed

10 files changed

+96
-43
lines changed

‎config/checkstyle-examples-suppressions.xml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,14 @@
7474
<suppress checks="Indent"
7575
files="nolinewrap[\\/]Example5.java"/>
7676

77+
<!-- multifileregexpheader examples use external XML configs instead of inline -->
78+
<suppress id="exampleFileXmlConfigPresence"
79+
files="multifileregexpheader[\\/]Example[1-4].java"/>
80+
<suppress id="xdocStartComment"
81+
files="multifileregexpheader[\\/]Example[1-4].java"/>
82+
<suppress id="xdocEndComment"
83+
files="multifileregexpheader[\\/]Example[1-4].java"/>
84+
7785
<!-- Check applies to resources-noncompilable files. -->
7886
<suppress id="presenceOfCompilationComment" files="resources[\\/].*"/>
7987

‎src/main/java/com/puppycrawl/tools/checkstyle/site/ExampleMacro.java‎

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -139,32 +139,69 @@ private static List<String> readFile(String path) throws MacroExecutionException
139139
/**
140140
* Extract a configuration snippet from the given lines. Config delimiters use the whole
141141
* line for themselves and have no indentation. We use equals() instead of contains()
142-
* to be more strict because some examples contain those delimiters.
142+
* to be more strict because some examples contain those delimiters. If the delimiters
143+
* are not found, returns the entire file content.
143144
*
144145
* @param lines the lines to extract the snippet from.
145146
* @return the configuration snippet.
146147
*/
147148
private static String getConfigSnippet(Collection<String> lines) {
148-
return lines.stream()
149+
final String snippet = lines.stream()
149150
.dropWhile(line -> !XML_CONFIG_START.equals(line))
150151
.skip(1)
151152
.takeWhile(line -> !XML_CONFIG_END.equals(line))
152153
.collect(Collectors.joining(ModuleJavadocParsingUtil.NEWLINE));
154+
155+
// If no snippet was found (markers not present), return the entire file content
156+
final String result;
157+
if (snippet.isBlank()) {
158+
result = String.join(ModuleJavadocParsingUtil.NEWLINE, lines);
159+
}
160+
else {
161+
result = snippet;
162+
}
163+
164+
return result;
153165
}
154166

155167
/**
156168
* Extract a code snippet from the given lines. Code delimiters can be indented, so
157-
* we use contains() instead of equals().
169+
* we use contains() instead of equals(). If the delimiters are not found, returns
170+
* the file content excluding the XML config block (if present).
158171
*
159172
* @param lines the lines to extract the snippet from.
160173
* @return the code snippet.
161174
*/
162175
private static String getCodeSnippet(Collection<String> lines) {
163-
return lines.stream()
176+
final String snippet = lines.stream()
164177
.dropWhile(line -> !line.contains(CODE_SNIPPET_START))
165178
.skip(1)
166179
.takeWhile(line -> !line.contains(CODE_SNIPPET_END))
167180
.collect(Collectors.joining(ModuleJavadocParsingUtil.NEWLINE));
181+
182+
// If no snippet was found (markers not present), return the file content
183+
// excluding the XML config block (if present)
184+
final String result;
185+
if (snippet.isBlank()) {
186+
final List<String> linesList = new ArrayList<>(lines);
187+
final int configEndIndex = linesList.indexOf(XML_CONFIG_END);
188+
if (configEndIndex >= 0) {
189+
// XML config block is present, return content after it
190+
result = String.join(ModuleJavadocParsingUtil.NEWLINE,
191+
linesList.stream()
192+
.skip(configEndIndex + 1)
193+
.toList());
194+
}
195+
else {
196+
// No XML config block, return entire file
197+
result = String.join(ModuleJavadocParsingUtil.NEWLINE, linesList);
198+
}
199+
}
200+
else {
201+
result = snippet;
202+
}
203+
204+
return result;
168205
}
169206

170207
/**

‎src/site/xdoc/checks/header/multifileregexpheader.xml‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,17 @@
4545
</subsection>
4646

4747
<subsection name="Examples" id="MultiFileRegexpHeader_Examples">
48-
<p id="Example1-config">
48+
<p id="Example1-raw">
4949
To configure the check such that no violations arise.
5050
Default values of properties are used.
5151
</p>
5252
<div class="wrapper"><pre class="prettyprint"><code class="language-xml">
53+
&lt;?xml version="1.0"?&gt;
54+
&lt;!DOCTYPE module PUBLIC
55+
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
56+
"https://checkstyle.org/dtds/configuration_1_3.dtd"&gt;
5357
&lt;module name="Checker"&gt;
54-
&lt;module name="MultiFileRegexpHeader"/&gt;
58+
&lt;module name="MultiFileRegexpHeader"/&gt;
5559
&lt;/module&gt;
5660
</code></pre></div>
5761

@@ -95,10 +99,13 @@ public class Example1 { }
9599

96100
<p id="Example2-code">Example2:</p>
97101
<div class="wrapper"><pre class="prettyprint"><code class="language-java">
102+
// Wrong header format
98103
package com.puppycrawl.tools.checkstyle.checks.header.multifileregexpheader;
99-
/* violation on first line 'Header mismatch, expected line content was' */
100-
// because headerFile is bigger then target java file
101-
public class Example2 { }
104+
105+
public class Example2 {
106+
// Some code
107+
}
108+
// violation 6 lines above 'Header mismatch, expected line content was'
102109
</code></pre></div>
103110
<hr class="example-separator"/>
104111

@@ -121,9 +128,14 @@ public class Example2 { }
121128

122129
<p id="Example3-code">Example3:</p>
123130
<div class="wrapper"><pre class="prettyprint"><code class="language-java">
131+
/* Licensed to the ASF under the Apache License, Version 2.0 (see NOTICE).
132+
* You may not use this file except in compliance:
133+
* http://www.apache.org/licenses/LICENSE-2.0 (AS IS, no warranties/conditions). */
124134
package com.puppycrawl.tools.checkstyle.checks.header.multifileregexpheader;
125-
/* violation on first line 'Header mismatch, expected line content was' */
126-
public class Example3 { }
135+
136+
public class Example3 {
137+
// Some code
138+
}
127139
</code></pre></div>
128140
<hr class="example-separator"/>
129141

@@ -153,8 +165,8 @@ public class Example3 { }
153165
<code>&quot;.*&quot;</code> matches all lines, so no violations are expected.
154166
</p>
155167
<div class="wrapper"><pre class="prettyprint"><code class="language-java">
168+
// Any header works here
156169
package com.puppycrawl.tools.checkstyle.checks.header.multifileregexpheader;
157-
// ok, as regex value matches all lines
158170
public class Example4 { }
159171
</code></pre></div>
160172

‎src/site/xdoc/checks/header/multifileregexpheader.xml.template‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,14 @@
2828
</subsection>
2929

3030
<subsection name="Examples" id="MultiFileRegexpHeader_Examples">
31-
<p id="Example1-config">
31+
<p id="Example1-raw">
3232
To configure the check such that no violations arise.
3333
Default values of properties are used.
3434
</p>
3535
<macro name="example">
3636
<param name="path"
37-
value="resources/com/puppycrawl/tools/checkstyle/checks/header/multifileregexpheader/Example1.java"/>
38-
<param name="type" value="config"/>
37+
value="resources/com/puppycrawl/tools/checkstyle/checks/header/multifileregexpheader/Example1.xml"/>
38+
<param name="type" value="raw"/>
3939
</macro>
4040

4141
<p id="Example1-code">Example1:</p>

‎src/xdocs-examples/java/com/puppycrawl/tools/checkstyle/checks/header/MultiFileRegexpHeaderCheckExamplesTest.java‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,9 @@ public String getPackageLocation() {
3333
@Test
3434
public void testExample1() throws Exception {
3535
final String[] expected = CommonUtil.EMPTY_STRING_ARRAY;
36-
verifyWithInlineConfigParser(getPath("Example1.java"), expected);
36+
verifyWithExternalXmlConfig(getPath("Example1.xml"),
37+
getPath("Example1.java"),
38+
expected);
3739
}
3840

3941
@Test

‎src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/header/multifileregexpheader/Example1.java‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
/*xml
2-
<module name="Checker">
3-
<module name="MultiFileRegexpHeader"/>
4-
</module>
5-
*/
6-
// xdoc section -- start
71
package com.puppycrawl.tools.checkstyle.checks.header.multifileregexpheader;
82
// ok, as by default there is not specific header defined to validate it presence
93
public class Example1 { }
10-
// xdoc section -- end

‎src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/header/multifileregexpheader/Example1.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<?xml version="1.0"?>
2+
<!DOCTYPE module PUBLIC
3+
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
4+
"https://checkstyle.org/dtds/configuration_1_3.dtd">
5+
<module name="Checker">
6+
<module name="MultiFileRegexpHeader"/>
7+
</module>

‎src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/header/multifileregexpheader/Example2.java‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
1-
/*xml
2-
*/
3-
// xdoc section -- start
1+
// Wrong header format
42
package com.puppycrawl.tools.checkstyle.checks.header.multifileregexpheader;
5-
/* violation on first line 'Header mismatch, expected line content was' */
6-
// because headerFile is bigger then target java file
7-
public class Example2 { }
8-
// xdoc section -- end
9-
// violation 8 lines above 'Header mismatch, expected line content was'
3+
4+
public class Example2 {
5+
// Some code
6+
}
7+
// violation 6 lines above 'Header mismatch, expected line content was'

‎src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/header/multifileregexpheader/Example3.java‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
/*xml
2-
*/
3-
// xdoc section -- start
1+
/* Licensed to the ASF under the Apache License, Version 2.0 (see NOTICE).
2+
* You may not use this file except in compliance:
3+
* http://www.apache.org/licenses/LICENSE-2.0 (AS IS, no warranties/conditions). */
44
package com.puppycrawl.tools.checkstyle.checks.header.multifileregexpheader;
5-
/* violation on first line 'Header mismatch, expected line content was' */
6-
public class Example3 { }
7-
// xdoc section -- end
8-
// violation 7 lines above 'Header mismatch, expected line content was'
5+
6+
public class Example3 {
7+
// Some code
8+
}

‎src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/header/multifileregexpheader/Example4.java‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
/*xml
2-
*/
3-
// xdoc section -- start
1+
// Any header works here
42
package com.puppycrawl.tools.checkstyle.checks.header.multifileregexpheader;
5-
// ok, as regex value matches all lines
63
public class Example4 { }
7-
// xdoc section -- end

0 commit comments

Comments
 (0)