Skip to content

Commit c307391

Browse files
jddarcyjddarcy
committed
8307184: Incorrect/inconsistent specification and implementation for Elements.getDocComment
Reviewed-by: vromero, jjg
1 parent 593ba2f commit c307391

File tree

2 files changed

+217
-6
lines changed

2 files changed

+217
-6
lines changed

‎src/java.compiler/share/classes/javax/lang/model/util/Elements.java

+26-6
Original file line numberDiff line numberDiff line change
@@ -283,22 +283,42 @@ default Set<? extends ModuleElement> getAllModuleElements() {
283283
* <p> A documentation comment of an element is a comment that
284284
* begins with "{@code /**}", ends with a separate
285285
* "<code>*&#47;</code>", and immediately precedes the element,
286-
* ignoring white space. Therefore, a documentation comment
286+
* ignoring white space, annotations, end-of-line-comments ({@code
287+
* "//"} comments), and intermediate traditional comments
288+
* (<code>"/* ... *&#47;"</code> comments) that are not doc comments.
289+
* Therefore, a documentation comment
287290
* contains at least three "{@code *}" characters. The text
288291
* returned for the documentation comment is a processed form of
289-
* the comment as it appears in source code. The leading "{@code /**}"
290-
* and trailing "<code>*&#47;</code>" are removed. For lines
291-
* of the comment starting after the initial "{@code /**}",
292-
* leading white space characters are discarded as are any
292+
* the comment as it appears in source code:
293+
* <ul>
294+
* <li>The leading "{@code /**}" is removed, as are any
295+
* immediately following space characters on that line. If all the
296+
* characters of the line are removed, it makes no contribution to
297+
* the returned comment.
298+
* <li>For subsequent lines
299+
* of the doc comment starting after the initial "{@code /**}",
300+
* if the lines start with <em>zero</em> or more whitespace characters followed by
301+
* <em>one</em> or more "{@code *}" characters,
302+
* those leading whitespace characters are discarded as are any
293303
* consecutive "{@code *}" characters appearing after the white
294-
* space or starting the line. The processed lines are then
304+
* space or starting the line.
305+
* Otherwise, if a line does not have a prefix of the described
306+
* form, the entire line is retained.
307+
* <li> The trailing "<code>*&#47;</code>" is removed. The line
308+
* with the trailing" <code>*&#47;</code>" also undergoes leading
309+
* space and "{@code *}" character removal as described above. If all the characters
310+
* of the line are removed, it makes no contribution to the
311+
* returned comment.
312+
* </ul>
313+
* The processed lines are then
295314
* concatenated together (including line terminators) and
296315
* returned.
297316
*
298317
* @param e the element being examined
299318
* @return the documentation comment of the element, or {@code null}
300319
* if there is none
301320
* @jls 3.6 White Space
321+
* @jls 3.7 Comments
302322
*/
303323
String getDocComment(Element e);
304324

‎test/langtools/tools/javac/processing/model/util/elements/TestGetDocComments.java

+191
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
/*
2+
* Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* This code is free software; you can redistribute it and/or modify it
6+
* under the terms of the GNU General Public License version 2 only, as
7+
* published by the Free Software Foundation.
8+
*
9+
* This code is distributed in the hope that it will be useful, but WITHOUT
10+
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11+
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12+
* version 2 for more details (a copy is included in the LICENSE file that
13+
* accompanied this code).
14+
*
15+
* You should have received a copy of the GNU General Public License version
16+
* 2 along with this work; if not, write to the Free Software Foundation,
17+
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18+
*
19+
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20+
* or visit www.oracle.com if you need additional information or have any
21+
* questions.
22+
*/
23+
24+
/*
25+
* @test
26+
* @bug 8307184
27+
* @summary Test basic operation of Elements.getDocComments
28+
* @library /tools/lib /tools/javac/lib
29+
* @build toolbox.ToolBox JavacTestingAbstractProcessor TestGetDocComments
30+
* @compile -processor TestGetDocComments -proc:only TestGetDocComments.java
31+
*/
32+
33+
import java.io.Writer;
34+
import java.util.*;
35+
import java.util.function.*;
36+
import javax.annotation.processing.*;
37+
import javax.lang.model.element.*;
38+
import javax.lang.model.util.*;
39+
import toolbox.ToolBox;
40+
41+
/**
42+
* Test basic workings of Elements.getDocComments
43+
*/
44+
public class TestGetDocComments extends JavacTestingAbstractProcessor {
45+
public boolean process(Set<? extends TypeElement> annotations,
46+
RoundEnvironment roundEnv) {
47+
if (!roundEnv.processingOver()) {
48+
boolean elementSeen = false;
49+
50+
for (TypeElement typeRoot : ElementFilter.typesIn(roundEnv.getRootElements()) ) {
51+
for (Element element : typeRoot.getEnclosedElements()) {
52+
ExpectedComment expectedComment = element.getAnnotation(ExpectedComment.class);
53+
if (expectedComment != null ) {
54+
elementSeen = true;
55+
String expectedCommentStr = expectedComment.value();
56+
String actualComment = elements.getDocComment(element);
57+
58+
if (!expectedCommentStr.equals(actualComment)) {
59+
messager.printError("Unexpected doc comment found", element);
60+
(new ToolBox()).checkEqual(expectedCommentStr.lines().toList(),
61+
actualComment.lines().toList());
62+
}
63+
}
64+
}
65+
66+
if (!elementSeen) {
67+
throw new RuntimeException("No elements seen.");
68+
}
69+
}
70+
}
71+
return true;
72+
}
73+
74+
@interface ExpectedComment {
75+
String value();
76+
}
77+
78+
// Basic processing of interior lines
79+
/**
80+
*Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
81+
*eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
82+
*enim ad minim veniam, quis nostrud exercitation ullamco laboris
83+
*nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
84+
*in reprehenderit in voluptate velit esse cillum dolore eu
85+
*fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
86+
*proident, sunt in culpa qui officia deserunt mollit anim id est
87+
*laborum.
88+
*/
89+
@ExpectedComment("""
90+
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
91+
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
92+
enim ad minim veniam, quis nostrud exercitation ullamco laboris
93+
nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
94+
in reprehenderit in voluptate velit esse cillum dolore eu
95+
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
96+
proident, sunt in culpa qui officia deserunt mollit anim id est
97+
laborum.
98+
""")
99+
// End-of-line-style comment
100+
@SuppressWarnings("") // A second preceding annotation
101+
/* Traditional comment */
102+
private void foo() {return ;}
103+
104+
105+
// Check removal of various *'s and space characters;
106+
// use Unicode escape to test tab removal
107+
/**
108+
*Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
109+
**eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
110+
***enim ad minim veniam, quis nostrud exercitation ullamco laboris
111+
*****nisi ut aliquip ex ea commodo consequat.
112+
\u0009*Duis aute irure dolor in reprehenderit in voluptate velit esse
113+
**cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
114+
***cupidatat non proident, sunt in culpa qui officia deserunt mollit
115+
*anim id est laborum.
116+
*/
117+
@ExpectedComment("""
118+
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
119+
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
120+
enim ad minim veniam, quis nostrud exercitation ullamco laboris
121+
nisi ut aliquip ex ea commodo consequat.
122+
Duis aute irure dolor in reprehenderit in voluptate velit esse
123+
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
124+
cupidatat non proident, sunt in culpa qui officia deserunt mollit
125+
anim id est laborum.
126+
""")
127+
@SuppressWarnings("") // A second preceding annotation
128+
// End-of-line-style comment
129+
/*
130+
* Traditional comment over multiple lines.
131+
*/
132+
private void bar() {return ;}
133+
134+
// Spaces _after_ the space-asterisk prefix are _not_ deleted.
135+
/**
136+
* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
137+
* eiusmod tempor incididunt ut labore et dolore magna aliqua.
138+
*/
139+
@ExpectedComment( // Cannot used a text block here since leading spaces are removed
140+
" Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do\n" +
141+
" eiusmod tempor incididunt ut labore et dolore magna aliqua.\n")
142+
private void baz() {return ;}
143+
144+
// Space after ** is removed, but not space before "*/"
145+
/** Totality */
146+
@ExpectedComment("Totality ") // No newline
147+
private void quux() {return ;}
148+
149+
// Space after "**" is removed, but not trailing space later on the line
150+
/** Totality\u0020
151+
*/
152+
@ExpectedComment("Totality \n")
153+
private void corge() {return ;}
154+
155+
/**
156+
* Totality */
157+
@ExpectedComment(" Totality ") // No newline
158+
private void grault() {return ;}
159+
160+
// Trailing space characters on first line
161+
/** \u0009\u0020
162+
* Totality
163+
*/
164+
@ExpectedComment(" Totality\n")
165+
private void wombat() {return ;}
166+
167+
/**
168+
*/
169+
@ExpectedComment("") // No newline
170+
private void empty() {return ;}
171+
172+
/**
173+
* tail */
174+
@ExpectedComment(" tail ") // No newline
175+
private void tail() {return ;}
176+
177+
/**
178+
****/
179+
@ExpectedComment("") // No newline
180+
private void tail2() {return ;}
181+
182+
// Testing of line terminators, javac implementation normalizes them:
183+
// * newline: \u000A
184+
// * carriage return: \u000D
185+
// * * carriage return + newline: \u000D\u000A
186+
/**
187+
* Lorem\u000A\u000D\u000D\u000Aipsum
188+
*/
189+
@ExpectedComment(" Lorem\n\n\nipsum\n")
190+
private void wombat2() {return ;}
191+
}

0 commit comments

Comments
 (0)