Skip to content
Permalink
Browse files
8258602: JavaDoc field summary does not indicate final modifier
Reviewed-by: jjg
  • Loading branch information
hns committed Apr 30, 2021
1 parent 276a1bf commit 07ecd421d1538ae53ffbea65eccfa938e19a9f0f
Show file tree
Hide file tree
Showing 8 changed files with 174 additions and 15 deletions.
@@ -243,6 +243,9 @@ private void addModifier(Element member, Content code) {
if (utils.isStatic(member)) {
code.add("static ");
}
if (!utils.isEnum(member) && utils.isFinal(member)) {
code.add("final ");
}
}

/**
@@ -75,7 +75,7 @@ public interface FieldWriter extends MemberWriter {
* Adds the preview output for the given member.
*
* @param member the member being documented
* @param annotationDocTree content tree to which the preview information will be added
* @param contentTree content tree to which the preview information will be added
*/
void addPreview(VariableElement member, Content contentTree);

@@ -402,6 +402,10 @@ public boolean isDefault(Element e) {
return e.getModifiers().contains(Modifier.DEFAULT);
}

public boolean isFinal(Element e) {
return e.getModifiers().contains(Modifier.FINAL);
}

public boolean isPackagePrivate(Element e) {
return !(isPublic(e) || isPrivate(e) || isProtected(e));
}
@@ -78,7 +78,7 @@ public void test1() {
<dl class="notes">
<dt>Property description:</dt>""",
"""
<div class="col-first odd-row-color"><code><a href="C.DoubleProperty.html" title\
<div class="col-first odd-row-color"><code>final <a href="C.DoubleProperty.html" title\
="class in pkg1">C.DoubleProperty</a></code></div>
<div class="col-second odd-row-color"><code><a href="#rateProperty" class="membe\
r-name-link">rate</a></code></div>
@@ -181,10 +181,10 @@ public void test1() {
<div class="caption"><span>Properties</span></div>
<div class="summary-table three-column-summary">""",
"""
<div class="col-first even-row-color"><code><a href="C.BooleanProperty.html" title="class in pkg1">C.BooleanProperty</a></code></div>
<div class="col-first even-row-color"><code>final <a href="C.BooleanProperty.html" title="class in pkg1">C.BooleanProperty</a></code></div>
""",
"""
<div class="col-first odd-row-color"><code><a href="C.DoubleProperty.html" title="class in pkg1">C.DoubleProperty</a></code></div>
<div class="col-first odd-row-color"><code>final <a href="C.DoubleProperty.html" title="class in pkg1">C.DoubleProperty</a></code></div>
""");

checkOutput("pkg1/C.html", false,
@@ -335,16 +335,16 @@ public void test3() {
<div class="col-last odd-row-color method-summary-table method-summary-table-tab\
2 method-summary-table-tab4">&nbsp;</div>
<div class="col-first even-row-color method-summary-table method-summary-table-t\
ab2 method-summary-table-tab4"><code>java.util.List&lt;java.util.Set&lt;? super \
java.lang.Object&gt;&gt;</code></div>
ab2 method-summary-table-tab4"><code>final java.util.List&lt;java.util.Set&lt;? \
super java.lang.Object&gt;&gt;</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-\
tab2 method-summary-table-tab4"><code><a href="#deltaProperty()" class="member-n\
ame-link">deltaProperty</a>()</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-ta\
b2 method-summary-table-tab4">&nbsp;</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-ta\
b2 method-summary-table-tab4"><code>java.util.List&lt;java.lang.String&gt;</code\
></div>
b2 method-summary-table-tab4"><code>final java.util.List&lt;java.lang.String&gt;\
</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-t\
ab2 method-summary-table-tab4"><code><a href="#gammaProperty()" class="member-na\
me-link">gammaProperty</a>()</code></div>
@@ -24,6 +24,7 @@
/*
* @test
* @bug 4951228 6290760 8025633 8026567 8081854 8162363 8175200 8177417 8186332 8182765
* 8258602
* @summary Test the case where the overridden method returns a different
* type than the method in the child class. Make sure the
* documentation is inherited but the return type isn't.
@@ -80,4 +81,101 @@ public void test() {
<h3 id="f(java.lang.Object[])">f</h3>
""");
}

@Test
public void testSummaries() {
javadoc("-d", "out-summaries",
"-private",
"-sourcepath", testSrc,
"pkg3");
checkExit(Exit.OK);
checkOutput("pkg3/Members.html", true,
"""
<div class="caption"><span>Nested Classes</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Class</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code>private static interface&nbsp;</code></div>
<div class="col-second even-row-color"><code><a href="Members.A.html" class="type-name-link" title="annotation interface in pkg3">Members.A</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><code>private static final class&nbsp;</code></div>
<div class="col-second odd-row-color"><code><a href="Members.C.html" class="type-name-link" title="class in pkg3">Members.C</a></code></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-first even-row-color"><code>private static class&nbsp;</code></div>
<div class="col-second even-row-color"><code><a href="Members.E.html" class="type-name-link" title="enum class in pkg3">Members.E</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><code>private static interface&nbsp;</code></div>
<div class="col-second odd-row-color"><code><a href="Members.I.html" class="type-name-link" title="interface in pkg3">Members.I</a></code></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-first even-row-color"><code>private static final class&nbsp;</code></div>
<div class="col-second even-row-color"><code><a href="Members.R.html" class="type-name-link" title="class in pkg3">Members.R</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""",
"""
<div class="caption"><span>Fields</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Field</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code>private static final int</code></div>
<div class="col-second even-row-color"><code><a href="#F" class="member-name-link">F</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""",
"""
<div class="caption"><span>Constructors</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier</div>
<div class="table-header col-second">Constructor</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code>private </code></div>
<div class="col-constructor-name even-row-color"><code><a href="#%3Cinit%3E()" class="member-name-link">Members</a>()</code></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>
""");
checkOutput("pkg3/Members.A.html", true,
"""
<div class="caption"><span>Required Elements</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Required Element</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code>int</code></div>
<div class="col-second even-row-color"><code><a href="#v()" class="member-name-link">v</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""",
"""
<div class="caption"><span>Optional Elements</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Optional Element</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code><a href="https://download.java.net/java/early_access/jdk17/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang" class="external-link">String</a></code></div>
<div class="col-second even-row-color"><code><a href="#s()" class="member-name-link">s</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>
""");
checkOutput("pkg3/Members.E.html", true,
"""
<h2>Enum Constant Summary</h2>
<div class="caption"><span>Enum Constants</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Enum Constant</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code><a href="#C" class="member-name-link">C</a></code></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""");
checkOutput("pkg3/Members.R.html", true,
"""
<div class="caption"><span>Fields</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Modifier and Type</div>
<div class="table-header col-second">Field</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><code>private final int</code></div>
<div class="col-second even-row-color"><code><a href="#i" class="member-name-link">i</a></code></div>
<div class="col-last even-row-color">
<div class="block">The field for the <code>i</code> record component.</div>
</div>""");
}
}
@@ -0,0 +1,54 @@
/*
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code 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
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/

package pkg3;

/**
* Test class for member and nested class summaries
*/
public class Members {

private Members() {}

private static final int F = 3;

private static final class C {}

private static final void M() {}

private enum E {
C;
}

private interface I {
default void i() {}
}

private @interface A {
int v();
String s() default "";
}

private record R(int i) {}

}
@@ -347,7 +347,7 @@ public void testSummary() {
<div class="block">This is Base::m5.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-ta\
b2 method-summary-table-tab4"><code>java.lang.Object</code></div>
b2 method-summary-table-tab4"><code>final java.lang.Object</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-t\
ab2 method-summary-table-tab4"><code><a href="#m6()" class="member-name-link">m6\
</a>()</code></div>
@@ -77,19 +77,19 @@ public void testArrays() {

// no tab classes should be used in the property table
"""
<div class="col-first even-row-color"><code><a href="ObjectProperty.html" title="clas\
s in pkg">ObjectProperty</a>&lt;<a href="MyObj.html" title="class in pkg">MyObj<\
/a>[]&gt;</code></div>
<div class="col-first even-row-color"><code>final <a href="ObjectProperty.html" \
title="class in pkg">ObjectProperty</a>&lt;<a href="MyObj.html" title="class in \
pkg">MyObj</a>[]&gt;</code></div>
<div class="col-second even-row-color"><code><a href="#badProperty" class="membe\
r-name-link">bad</a></code></div>
<div class="col-last even-row-color">""",

// tab classes should be used in the method table
"""
<div class="col-first even-row-color method-summary-table method-summary-table-t\
ab2 method-summary-table-tab4"><code><a href="ObjectProperty.html" title="class in pk\
g">ObjectProperty</a>&lt;<a href="MyObj.html" title="class in pkg">MyObj</a>[]&g\
t;</code></div>
ab2 method-summary-table-tab4"><code>final <a href="ObjectProperty.html" title="\
class in pkg">ObjectProperty</a>&lt;<a href="MyObj.html" title="class in pkg">My\
Obj</a>[]&gt;</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-\
tab2 method-summary-table-tab4"><code><a href="#badProperty()" class="member-nam\
e-link">badProperty</a>()</code></div>"""

1 comment on commit 07ecd42

@openjdk-notifier
Copy link

@openjdk-notifier openjdk-notifier bot commented on 07ecd42 Apr 30, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.