8015249: javadoc fails to document static final fields in annotation types
Reviewed-by: jjg
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/AnnotationTypeFieldWriterImpl.java Wed Sep 18 17:13:26 2013 -0700
@@ -0,0 +1,301 @@
+/*
+ * Copyright (c) 2013, 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. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * 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 com.sun.tools.doclets.formats.html;
+
+import java.io.*;
+
+import com.sun.javadoc.*;
+import com.sun.tools.doclets.formats.html.markup.*;
+import com.sun.tools.doclets.internal.toolkit.*;
+
+/**
+ * Writes annotation type field documentation in HTML format.
+ *
+ * <p><b>This is NOT part of any supported API.
+ * If you write code that depends on this, you do so at your own risk.
+ * This code and its internal interfaces are subject to change or
+ * deletion without notice.</b>
+ *
+ * @author Bhavesh Patel
+ */
+public class AnnotationTypeFieldWriterImpl extends AbstractMemberWriter
+ implements AnnotationTypeFieldWriter, MemberSummaryWriter {
+
+ /**
+ * Construct a new AnnotationTypeFieldWriterImpl.
+ *
+ * @param writer the writer that will write the output.
+ * @param annotationType the AnnotationType that holds this member.
+ */
+ public AnnotationTypeFieldWriterImpl(SubWriterHolderWriter writer,
+ AnnotationTypeDoc annotationType) {
+ super(writer, annotationType);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public Content getMemberSummaryHeader(ClassDoc classDoc,
+ Content memberSummaryTree) {
+ memberSummaryTree.addContent(
+ HtmlConstants.START_OF_ANNOTATION_TYPE_FIELD_SUMMARY);
+ Content memberTree = writer.getMemberTreeHeader();
+ writer.addSummaryHeader(this, classDoc, memberTree);
+ return memberTree;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public Content getMemberTreeHeader() {
+ return writer.getMemberTreeHeader();
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addAnnotationFieldDetailsMarker(Content memberDetails) {
+ memberDetails.addContent(HtmlConstants.START_OF_ANNOTATION_TYPE_FIELD_DETAILS);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addAnnotationDetailsTreeHeader(ClassDoc classDoc,
+ Content memberDetailsTree) {
+ if (!writer.printedAnnotationFieldHeading) {
+ memberDetailsTree.addContent(writer.getMarkerAnchor(
+ "annotation_type_field_detail"));
+ Content heading = HtmlTree.HEADING(HtmlConstants.DETAILS_HEADING,
+ writer.fieldDetailsLabel);
+ memberDetailsTree.addContent(heading);
+ writer.printedAnnotationFieldHeading = true;
+ }
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public Content getAnnotationDocTreeHeader(MemberDoc member,
+ Content annotationDetailsTree) {
+ annotationDetailsTree.addContent(
+ writer.getMarkerAnchor(member.name()));
+ Content annotationDocTree = writer.getMemberTreeHeader();
+ Content heading = new HtmlTree(HtmlConstants.MEMBER_HEADING);
+ heading.addContent(member.name());
+ annotationDocTree.addContent(heading);
+ return annotationDocTree;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public Content getSignature(MemberDoc member) {
+ Content pre = new HtmlTree(HtmlTag.PRE);
+ writer.addAnnotationInfo(member, pre);
+ addModifiers(member, pre);
+ Content link =
+ writer.getLink(new LinkInfoImpl(configuration,
+ LinkInfoImpl.Kind.MEMBER, getType(member)));
+ pre.addContent(link);
+ pre.addContent(writer.getSpace());
+ if (configuration.linksource) {
+ Content memberName = new StringContent(member.name());
+ writer.addSrcLink(member, memberName, pre);
+ } else {
+ addName(member.name(), pre);
+ }
+ return pre;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addDeprecated(MemberDoc member, Content annotationDocTree) {
+ addDeprecatedInfo(member, annotationDocTree);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addComments(MemberDoc member, Content annotationDocTree) {
+ addComment(member, annotationDocTree);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addTags(MemberDoc member, Content annotationDocTree) {
+ writer.addTagsInfo(member, annotationDocTree);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public Content getAnnotationDetails(Content annotationDetailsTree) {
+ return getMemberTree(annotationDetailsTree);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public Content getAnnotationDoc(Content annotationDocTree,
+ boolean isLastContent) {
+ return getMemberTree(annotationDocTree, isLastContent);
+ }
+
+ /**
+ * Close the writer.
+ */
+ public void close() throws IOException {
+ writer.close();
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addSummaryLabel(Content memberTree) {
+ Content label = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING,
+ writer.getResource("doclet.Field_Summary"));
+ memberTree.addContent(label);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String getTableSummary() {
+ return configuration.getText("doclet.Member_Table_Summary",
+ configuration.getText("doclet.Field_Summary"),
+ configuration.getText("doclet.fields"));
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public Content getCaption() {
+ return configuration.getResource("doclet.Fields");
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String[] getSummaryTableHeader(ProgramElementDoc member) {
+ String[] header = new String[] {
+ writer.getModifierTypeHeader(),
+ configuration.getText("doclet.0_and_1",
+ configuration.getText("doclet.Fields"),
+ configuration.getText("doclet.Description"))
+ };
+ return header;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addSummaryAnchor(ClassDoc cd, Content memberTree) {
+ memberTree.addContent(writer.getMarkerAnchor(
+ "annotation_type_field_summary"));
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addInheritedSummaryAnchor(ClassDoc cd, Content inheritedTree) {
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addInheritedSummaryLabel(ClassDoc cd, Content inheritedTree) {
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ protected void addSummaryLink(LinkInfoImpl.Kind context, ClassDoc cd, ProgramElementDoc member,
+ Content tdSummary) {
+ Content strong = HtmlTree.SPAN(HtmlStyle.strong,
+ writer.getDocLink(context, (MemberDoc) member, member.name(), false));
+ Content code = HtmlTree.CODE(strong);
+ tdSummary.addContent(code);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ protected void addInheritedSummaryLink(ClassDoc cd,
+ ProgramElementDoc member, Content linksTree) {
+ //Not applicable.
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ protected void addSummaryType(ProgramElementDoc member, Content tdSummaryType) {
+ MemberDoc m = (MemberDoc)member;
+ addModifierAndType(m, getType(m), tdSummaryType);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ protected Content getDeprecatedLink(ProgramElementDoc member) {
+ return writer.getDocLink(LinkInfoImpl.Kind.MEMBER,
+ (MemberDoc) member, ((MemberDoc)member).qualifiedName());
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ protected Content getNavSummaryLink(ClassDoc cd, boolean link) {
+ if (link) {
+ return writer.getHyperLink("annotation_type_field_summary",
+ writer.getResource("doclet.navField"));
+ } else {
+ return writer.getResource("doclet.navField");
+ }
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ protected void addNavDetailLink(boolean link, Content liNav) {
+ if (link) {
+ liNav.addContent(writer.getHyperLink("annotation_type_field_detail",
+ writer.getResource("doclet.navField")));
+ } else {
+ liNav.addContent(writer.getResource("doclet.navField"));
+ }
+ }
+
+ private Type getType(MemberDoc member) {
+ if (member instanceof FieldDoc) {
+ return ((FieldDoc) member).type();
+ } else {
+ return ((MethodDoc) member).returnType();
+ }
+ }
+}
--- a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/AnnotationTypeRequiredMemberWriterImpl.java Wed Sep 18 17:13:26 2013 -0700
@@ -71,6 +71,20 @@
/**
* {@inheritDoc}
*/
+ public Content getMemberTreeHeader() {
+ return writer.getMemberTreeHeader();
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public void addAnnotationDetailsMarker(Content memberDetails) {
+ memberDetails.addContent(HtmlConstants.START_OF_ANNOTATION_TYPE_DETAILS);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
public void addAnnotationDetailsTreeHeader(ClassDoc classDoc,
Content memberDetailsTree) {
if (!writer.printedAnnotationHeading) {
--- a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/AnnotationTypeWriterImpl.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/AnnotationTypeWriterImpl.java Wed Sep 18 17:13:26 2013 -0700
@@ -278,13 +278,6 @@
/**
* {@inheritDoc}
*/
- public void addAnnotationDetailsMarker(Content memberDetails) {
- memberDetails.addContent(HtmlConstants.START_OF_ANNOTATION_TYPE_DETAILS);
- }
-
- /**
- * {@inheritDoc}
- */
protected Content getNavLinkTree() {
Content treeLinkContent = getHyperLink(DocPaths.PACKAGE_TREE,
treeLabel, "", "");
@@ -319,6 +312,12 @@
Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
MemberSummaryBuilder memberSummaryBuilder = (MemberSummaryBuilder)
configuration.getBuilderFactory().getMemberSummaryBuilder(this);
+ Content liNavField = new HtmlTree(HtmlTag.LI);
+ addNavSummaryLink(memberSummaryBuilder,
+ "doclet.navField",
+ VisibleMemberMap.ANNOTATION_TYPE_FIELDS, liNavField);
+ addNavGap(liNavField);
+ ulNav.addContent(liNavField);
Content liNavReq = new HtmlTree(HtmlTag.LI);
addNavSummaryLink(memberSummaryBuilder,
"doclet.navAnnotationTypeRequiredMember",
@@ -364,12 +363,23 @@
Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
MemberSummaryBuilder memberSummaryBuilder = (MemberSummaryBuilder)
configuration.getBuilderFactory().getMemberSummaryBuilder(this);
+ AbstractMemberWriter writerField =
+ ((AbstractMemberWriter) memberSummaryBuilder.
+ getMemberSummaryWriter(VisibleMemberMap.ANNOTATION_TYPE_FIELDS));
AbstractMemberWriter writerOptional =
((AbstractMemberWriter) memberSummaryBuilder.
getMemberSummaryWriter(VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL));
AbstractMemberWriter writerRequired =
((AbstractMemberWriter) memberSummaryBuilder.
getMemberSummaryWriter(VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED));
+ Content liNavField = new HtmlTree(HtmlTag.LI);
+ if (writerField != null){
+ writerField.addNavDetailLink(annotationType.fields().length > 0, liNavField);
+ } else {
+ liNavField.addContent(getResource("doclet.navField"));
+ }
+ addNavGap(liNavField);
+ ulNav.addContent(liNavField);
if (writerOptional != null){
Content liNavOpt = new HtmlTree(HtmlTag.LI);
writerOptional.addNavDetailLink(annotationType.elements().length > 0, liNavOpt);
--- a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java Wed Sep 18 17:13:26 2013 -0700
@@ -85,6 +85,11 @@
protected boolean printedAnnotationHeading = false;
/**
+ * To check whether annotation field heading is printed or not.
+ */
+ protected boolean printedAnnotationFieldHeading = false;
+
+ /**
* To check whether the repeated annotations is documented or not.
*/
private boolean isAnnotationDocumented = false;
--- a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/WriterFactoryImpl.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/WriterFactoryImpl.java Wed Sep 18 17:13:26 2013 -0700
@@ -107,6 +107,16 @@
/**
* {@inheritDoc}
*/
+ public AnnotationTypeFieldWriter
+ getAnnotationTypeFieldWriter(AnnotationTypeWriter annotationTypeWriter) throws Exception {
+ return new AnnotationTypeFieldWriterImpl(
+ (SubWriterHolderWriter) annotationTypeWriter,
+ annotationTypeWriter.getAnnotationTypeDoc());
+ }
+
+ /**
+ * {@inheritDoc}
+ */
public AnnotationTypeOptionalMemberWriter
getAnnotationTypeOptionalMemberWriter(
AnnotationTypeWriter annotationTypeWriter) throws Exception {
@@ -202,6 +212,9 @@
AnnotationTypeWriter annotationTypeWriter, int memberType)
throws Exception {
switch (memberType) {
+ case VisibleMemberMap.ANNOTATION_TYPE_FIELDS:
+ return (AnnotationTypeFieldWriterImpl)
+ getAnnotationTypeFieldWriter(annotationTypeWriter);
case VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL:
return (AnnotationTypeOptionalMemberWriterImpl)
getAnnotationTypeOptionalMemberWriter(annotationTypeWriter);
--- a/langtools/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlConstants.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlConstants.java Wed Sep 18 17:13:26 2013 -0700
@@ -94,6 +94,12 @@
new Comment("=========== ANNOTATION TYPE REQUIRED MEMBER SUMMARY ===========");
/**
+ * Marker to identify start of annotation type required member summary.
+ */
+ public static final Content START_OF_ANNOTATION_TYPE_FIELD_SUMMARY =
+ new Comment("=========== ANNOTATION TYPE FIELD SUMMARY ===========");
+
+ /**
* Marker to identify start of constructor summary.
*/
public static final Content START_OF_CONSTRUCTOR_SUMMARY =
@@ -130,6 +136,12 @@
new Comment("============ ANNOTATION TYPE MEMBER DETAIL ===========");
/**
+ * Marker to identify start of annotation type field details.
+ */
+ public static final Content START_OF_ANNOTATION_TYPE_FIELD_DETAILS =
+ new Comment("============ ANNOTATION TYPE FIELD DETAIL ===========");
+
+ /**
* Marker to identify start of method details.
*/
public static final Content START_OF_METHOD_DETAILS =
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/AnnotationTypeFieldWriter.java Wed Sep 18 17:13:26 2013 -0700
@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2013, 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. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * 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 com.sun.tools.doclets.internal.toolkit;
+
+import java.io.*;
+import com.sun.javadoc.*;
+
+/**
+ * The interface for writing annotation type field output.
+ *
+ * <p><b>This is NOT part of any supported API.
+ * If you write code that depends on this, you do so at your own risk.
+ * This code and its internal interfaces are subject to change or
+ * deletion without notice.</b>
+ *
+ *
+ * @author Bhavesh Patel
+ * @since 1.8
+ */
+
+public interface AnnotationTypeFieldWriter {
+
+ /**
+ * Add the annotation type member tree header.
+ *
+ * @return content tree for the member tree header
+ */
+ public Content getMemberTreeHeader();
+
+ /**
+ * Add the annotation type field details marker.
+ *
+ * @param memberDetails the content tree representing field details marker
+ */
+ public void addAnnotationFieldDetailsMarker(Content memberDetails);
+
+ /**
+ * Add the annotation type details tree header.
+ *
+ * @param classDoc the annotation type being documented
+ * @param memberDetailsTree the content tree representing member details
+ */
+ public void addAnnotationDetailsTreeHeader(ClassDoc classDoc,
+ Content memberDetailsTree);
+
+ /**
+ * Get the annotation type documentation tree header.
+ *
+ * @param member the annotation type being documented
+ * @param annotationDetailsTree the content tree representing annotation type details
+ * @return content tree for the annotation type documentation header
+ */
+ public Content getAnnotationDocTreeHeader(MemberDoc member,
+ Content annotationDetailsTree);
+
+ /**
+ * Get the annotation type details tree.
+ *
+ * @param annotationDetailsTree the content tree representing annotation type details
+ * @return content tree for the annotation type details
+ */
+ public Content getAnnotationDetails(Content annotationDetailsTree);
+
+ /**
+ * Get the annotation type documentation.
+ *
+ * @param annotationDocTree the content tree representing annotation type documentation
+ * @param isLastContent true if the content to be added is the last content
+ * @return content tree for the annotation type documentation
+ */
+ public Content getAnnotationDoc(Content annotationDocTree, boolean isLastContent);
+
+ /**
+ * Get the signature for the given member.
+ *
+ * @param member the member being documented
+ * @return content tree for the annotation type signature
+ */
+ public Content getSignature(MemberDoc member);
+
+ /**
+ * Add the deprecated output for the given member.
+ *
+ * @param member the member being documented
+ * @param annotationDocTree content tree to which the deprecated information will be added
+ */
+ public void addDeprecated(MemberDoc member, Content annotationDocTree);
+
+ /**
+ * Add the comments for the given member.
+ *
+ * @param member the member being documented
+ * @param annotationDocTree the content tree to which the comments will be added
+ */
+ public void addComments(MemberDoc member, Content annotationDocTree);
+
+ /**
+ * Add the tags for the given member.
+ *
+ * @param member the member being documented
+ * @param annotationDocTree the content tree to which the tags will be added
+ */
+ public void addTags(MemberDoc member, Content annotationDocTree);
+
+ /**
+ * Close the writer.
+ */
+ public void close() throws IOException;
+}
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/AnnotationTypeRequiredMemberWriter.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/AnnotationTypeRequiredMemberWriter.java Wed Sep 18 17:13:26 2013 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2013, 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
@@ -45,6 +45,20 @@
public interface AnnotationTypeRequiredMemberWriter {
/**
+ * Add the annotation type member tree header.
+ *
+ * @return content tree for the member tree header
+ */
+ public Content getMemberTreeHeader();
+
+ /**
+ * Add the annotation type details marker.
+ *
+ * @param memberDetails the content tree representing details marker
+ */
+ public void addAnnotationDetailsMarker(Content memberDetails);
+
+ /**
* Add the annotation type details tree header.
*
* @param classDoc the annotation type being documented
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/AnnotationTypeWriter.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/AnnotationTypeWriter.java Wed Sep 18 17:13:26 2013 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2013, 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
@@ -104,13 +104,6 @@
public void addAnnotationTypeDeprecationInfo (Content annotationInfoTree);
/**
- * Add the annotation type details marker.
- *
- * @param memberDetails the content tree representing member details marker
- */
- public void addAnnotationDetailsMarker(Content memberDetails);
-
- /**
* Get the member tree header for the annotation type.
*
* @return a content tree for the member tree header
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/WriterFactory.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/WriterFactory.java Wed Sep 18 17:13:26 2013 -0700
@@ -130,6 +130,18 @@
throws Exception;
/**
+ * Return the annotation type field writer for a given annotation type.
+ *
+ * @param annotationTypeWriter the writer for the annotation type
+ * being documented.
+ * @return the member writer for the given annotation type. Return null if
+ * this writer is not supported by the doclet.
+ */
+ public abstract AnnotationTypeFieldWriter
+ getAnnotationTypeFieldWriter(
+ AnnotationTypeWriter annotationTypeWriter) throws Exception;
+
+ /**
* Return the annotation type optional member writer for a given annotation
* type.
*
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeBuilder.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeBuilder.java Wed Sep 18 17:13:26 2013 -0700
@@ -223,14 +223,23 @@
Content memberDetailsTree = writer.getMemberTreeHeader();
buildChildren(node, memberDetailsTree);
if (memberDetailsTree.isValid()) {
- Content memberDetails = writer.getMemberTreeHeader();
- writer.addAnnotationDetailsMarker(memberDetails);
- memberDetails.addContent(writer.getMemberTree(memberDetailsTree));
- annotationContentTree.addContent(writer.getMemberDetailsTree(memberDetails));
+ annotationContentTree.addContent(writer.getMemberDetailsTree(memberDetailsTree));
}
}
/**
+ * Build the annotation type field documentation.
+ *
+ * @param node the XML element that specifies which components to document
+ * @param memberDetailsTree the content tree to which the documentation will be added
+ */
+ public void buildAnnotationTypeFieldDetails(XMLNode node, Content memberDetailsTree)
+ throws Exception {
+ configuration.getBuilderFactory().
+ getAnnotationTypeFieldsBuilder(writer).buildChildren(node, memberDetailsTree);
+ }
+
+ /**
* Build the annotation type optional member documentation.
*
* @param node the XML element that specifies which components to document
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeFieldBuilder.java Wed Sep 18 17:13:26 2013 -0700
@@ -0,0 +1,240 @@
+/*
+ * Copyright (c) 2013, 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. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * 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 com.sun.tools.doclets.internal.toolkit.builders;
+
+import java.util.*;
+
+import com.sun.javadoc.*;
+import com.sun.tools.doclets.internal.toolkit.*;
+import com.sun.tools.doclets.internal.toolkit.util.*;
+
+/**
+ * Builds documentation for annotation type fields.
+ *
+ * <p><b>This is NOT part of any supported API.
+ * If you write code that depends on this, you do so at your own risk.
+ * This code and its internal interfaces are subject to change or
+ * deletion without notice.</b>
+ *
+ * @author Bhavesh Patel
+ * @since 1.8
+ */
+public class AnnotationTypeFieldBuilder extends AbstractMemberBuilder {
+
+ /**
+ * The annotation type whose members are being documented.
+ */
+ protected ClassDoc classDoc;
+
+ /**
+ * The visible members for the given class.
+ */
+ protected VisibleMemberMap visibleMemberMap;
+
+ /**
+ * The writer to output the member documentation.
+ */
+ protected AnnotationTypeFieldWriter writer;
+
+ /**
+ * The list of members being documented.
+ */
+ protected List<ProgramElementDoc> members;
+
+ /**
+ * The index of the current member that is being documented at this point
+ * in time.
+ */
+ protected int currentMemberIndex;
+
+ /**
+ * Construct a new AnnotationTypeFieldsBuilder.
+ *
+ * @param context the build context.
+ * @param classDoc the class whose members are being documented.
+ * @param writer the doclet specific writer.
+ * @param memberType the type of member that is being documented.
+ */
+ protected AnnotationTypeFieldBuilder(Context context,
+ ClassDoc classDoc,
+ AnnotationTypeFieldWriter writer,
+ int memberType) {
+ super(context);
+ this.classDoc = classDoc;
+ this.writer = writer;
+ this.visibleMemberMap = new VisibleMemberMap(classDoc, memberType,
+ configuration);
+ this.members = new ArrayList<ProgramElementDoc>(
+ this.visibleMemberMap.getMembersFor(classDoc));
+ if (configuration.getMemberComparator() != null) {
+ Collections.sort(this.members, configuration.getMemberComparator());
+ }
+ }
+
+
+ /**
+ * Construct a new AnnotationTypeFieldBuilder.
+ *
+ * @param context the build context.
+ * @param classDoc the class whose members are being documented.
+ * @param writer the doclet specific writer.
+ */
+ public static AnnotationTypeFieldBuilder getInstance(
+ Context context, ClassDoc classDoc,
+ AnnotationTypeFieldWriter writer) {
+ return new AnnotationTypeFieldBuilder(context, classDoc,
+ writer, VisibleMemberMap.ANNOTATION_TYPE_FIELDS);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ public String getName() {
+ return "AnnotationTypeFieldDetails";
+ }
+
+ /**
+ * Returns a list of members that will be documented for the given class.
+ * This information can be used for doclet specific documentation
+ * generation.
+ *
+ * @param classDoc the {@link ClassDoc} we want to check.
+ * @return a list of members that will be documented.
+ */
+ public List<ProgramElementDoc> members(ClassDoc classDoc) {
+ return visibleMemberMap.getMembersFor(classDoc);
+ }
+
+ /**
+ * Returns the visible member map for the members of this class.
+ *
+ * @return the visible member map for the members of this class.
+ */
+ public VisibleMemberMap getVisibleMemberMap() {
+ return visibleMemberMap;
+ }
+
+ /**
+ * summaryOrder.size()
+ */
+ public boolean hasMembersToDocument() {
+ return members.size() > 0;
+ }
+
+ /**
+ * Build the annotation type field documentation.
+ *
+ * @param node the XML element that specifies which components to document
+ * @param memberDetailsTree the content tree to which the documentation will be added
+ */
+ public void buildAnnotationTypeField(XMLNode node, Content memberDetailsTree) {
+ buildAnnotationTypeMember(node, memberDetailsTree);
+ }
+
+ /**
+ * Build the member documentation.
+ *
+ * @param node the XML element that specifies which components to document
+ * @param memberDetailsTree the content tree to which the documentation will be added
+ */
+ public void buildAnnotationTypeMember(XMLNode node, Content memberDetailsTree) {
+ if (writer == null) {
+ return;
+ }
+ int size = members.size();
+ if (size > 0) {
+ writer.addAnnotationFieldDetailsMarker(memberDetailsTree);
+ for (currentMemberIndex = 0; currentMemberIndex < size;
+ currentMemberIndex++) {
+ Content detailsTree = writer.getMemberTreeHeader();
+ writer.addAnnotationDetailsTreeHeader(classDoc, detailsTree);
+ Content annotationDocTree = writer.getAnnotationDocTreeHeader(
+ (MemberDoc) members.get(currentMemberIndex),
+ detailsTree);
+ buildChildren(node, annotationDocTree);
+ detailsTree.addContent(writer.getAnnotationDoc(
+ annotationDocTree, (currentMemberIndex == size - 1)));
+ memberDetailsTree.addContent(writer.getAnnotationDetails(detailsTree));
+ }
+ }
+ }
+
+ /**
+ * Build the signature.
+ *
+ * @param node the XML element that specifies which components to document
+ * @param annotationDocTree the content tree to which the documentation will be added
+ */
+ public void buildSignature(XMLNode node, Content annotationDocTree) {
+ annotationDocTree.addContent(
+ writer.getSignature((MemberDoc) members.get(currentMemberIndex)));
+ }
+
+ /**
+ * Build the deprecation information.
+ *
+ * @param node the XML element that specifies which components to document
+ * @param annotationDocTree the content tree to which the documentation will be added
+ */
+ public void buildDeprecationInfo(XMLNode node, Content annotationDocTree) {
+ writer.addDeprecated((MemberDoc) members.get(currentMemberIndex),
+ annotationDocTree);
+ }
+
+ /**
+ * Build the comments for the member. Do nothing if
+ * {@link Configuration#nocomment} is set to true.
+ *
+ * @param node the XML element that specifies which components to document
+ * @param annotationDocTree the content tree to which the documentation will be added
+ */
+ public void buildMemberComments(XMLNode node, Content annotationDocTree) {
+ if(! configuration.nocomment){
+ writer.addComments((MemberDoc) members.get(currentMemberIndex),
+ annotationDocTree);
+ }
+ }
+
+ /**
+ * Build the tag information.
+ *
+ * @param node the XML element that specifies which components to document
+ * @param annotationDocTree the content tree to which the documentation will be added
+ */
+ public void buildTagInfo(XMLNode node, Content annotationDocTree) {
+ writer.addTags((MemberDoc) members.get(currentMemberIndex),
+ annotationDocTree);
+ }
+
+ /**
+ * Return the annotation type field writer for this builder.
+ *
+ * @return the annotation type field writer for this builder.
+ */
+ public AnnotationTypeFieldWriter getWriter() {
+ return writer;
+ }
+}
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeRequiredMemberBuilder.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AnnotationTypeRequiredMemberBuilder.java Wed Sep 18 17:13:26 2013 -0700
@@ -167,16 +167,17 @@
}
int size = members.size();
if (size > 0) {
- writer.addAnnotationDetailsTreeHeader(
- classDoc, memberDetailsTree);
+ writer.addAnnotationDetailsMarker(memberDetailsTree);
for (currentMemberIndex = 0; currentMemberIndex < size;
- currentMemberIndex++) {
+ currentMemberIndex++) {
+ Content detailsTree = writer.getMemberTreeHeader();
+ writer.addAnnotationDetailsTreeHeader(classDoc, detailsTree);
Content annotationDocTree = writer.getAnnotationDocTreeHeader(
- (MemberDoc) members.get(currentMemberIndex),
- memberDetailsTree);
+ (MemberDoc) members.get(currentMemberIndex), detailsTree);
buildChildren(node, annotationDocTree);
- memberDetailsTree.addContent(writer.getAnnotationDoc(
+ detailsTree.addContent(writer.getAnnotationDoc(
annotationDocTree, (currentMemberIndex == size - 1)));
+ memberDetailsTree.addContent(writer.getAnnotationDetails(detailsTree));
}
}
}
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/BuilderFactory.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/BuilderFactory.java Wed Sep 18 17:13:26 2013 -0700
@@ -174,10 +174,26 @@
}
/**
+ * Return an instance of the annotation type fields builder for the given
+ * class.
+ *
+ * @return an instance of the annotation type field builder for the given
+ * annotation type.
+ */
+ public AbstractBuilder getAnnotationTypeFieldsBuilder(
+ AnnotationTypeWriter annotationTypeWriter)
+ throws Exception {
+ return AnnotationTypeFieldBuilder.getInstance(context,
+ annotationTypeWriter.getAnnotationTypeDoc(),
+ writerFactory.getAnnotationTypeFieldWriter(
+ annotationTypeWriter));
+ }
+
+ /**
* Return an instance of the annotation type member builder for the given
* class.
*
- * @return an instance of the annotation type memebr builder for the given
+ * @return an instance of the annotation type member builder for the given
* annotation type.
*/
public AbstractBuilder getAnnotationTypeOptionalMemberBuilder(
@@ -193,7 +209,7 @@
* Return an instance of the annotation type member builder for the given
* class.
*
- * @return an instance of the annotation type memebr builder for the given
+ * @return an instance of the annotation type member builder for the given
* annotation type.
*/
public AbstractBuilder getAnnotationTypeRequiredMemberBuilder(
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/builders/MemberSummaryBuilder.java Wed Sep 18 17:13:26 2013 -0700
@@ -213,6 +213,20 @@
}
/**
+ * Build the summary for fields.
+ *
+ * @param node the XML element that specifies which components to document
+ * @param memberSummaryTree the content tree to which the documentation will be added
+ */
+ public void buildAnnotationTypeFieldsSummary(XMLNode node, Content memberSummaryTree) {
+ MemberSummaryWriter writer =
+ memberSummaryWriters[VisibleMemberMap.ANNOTATION_TYPE_FIELDS];
+ VisibleMemberMap visibleMemberMap =
+ visibleMemberMaps[VisibleMemberMap.ANNOTATION_TYPE_FIELDS];
+ addSummary(writer, visibleMemberMap, false, memberSummaryTree);
+ }
+
+ /**
* Build the summary for the optional members.
*
* @param node the XML element that specifies which components to document
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/resources/doclet.xml Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/resources/doclet.xml Wed Sep 18 17:13:26 2013 -0700
@@ -66,10 +66,19 @@
<AnnotationTypeTagInfo/>
</AnnotationTypeInfo>
<MemberSummary>
+ <AnnotationTypeFieldsSummary/>
<AnnotationTypeRequiredMemberSummary/>
<AnnotationTypeOptionalMemberSummary/>
</MemberSummary>
<AnnotationTypeMemberDetails>
+ <AnnotationTypeFieldDetails>
+ <AnnotationTypeField>
+ <Signature/>
+ <DeprecationInfo/>
+ <MemberComments/>
+ <TagInfo/>
+ </AnnotationTypeField>
+ </AnnotationTypeFieldDetails>
<AnnotationTypeRequiredMemberDetails>
<AnnotationTypeRequiredMember>
<Signature/>
--- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/VisibleMemberMap.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/VisibleMemberMap.java Wed Sep 18 17:13:26 2013 -0700
@@ -55,14 +55,15 @@
public static final int FIELDS = 2;
public static final int CONSTRUCTORS = 3;
public static final int METHODS = 4;
- public static final int ANNOTATION_TYPE_MEMBER_OPTIONAL = 5;
- public static final int ANNOTATION_TYPE_MEMBER_REQUIRED = 6;
- public static final int PROPERTIES = 7;
+ public static final int ANNOTATION_TYPE_FIELDS = 5;
+ public static final int ANNOTATION_TYPE_MEMBER_OPTIONAL = 6;
+ public static final int ANNOTATION_TYPE_MEMBER_REQUIRED = 7;
+ public static final int PROPERTIES = 8;
/**
* The total number of member types is {@value}.
*/
- public static final int NUM_MEMBER_TYPES = 8;
+ public static final int NUM_MEMBER_TYPES = 9;
public static final String STARTLEVEL = "start";
@@ -433,6 +434,9 @@
}
ProgramElementDoc[] members = null;
switch (kind) {
+ case ANNOTATION_TYPE_FIELDS:
+ members = cd.fields(filter);
+ break;
case ANNOTATION_TYPE_MEMBER_OPTIONAL:
members = cd.isAnnotationType() ?
filter((AnnotationTypeDoc) cd, false) :
--- a/langtools/test/com/sun/javadoc/testAnnotationTypes/TestAnnotationTypes.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/test/com/sun/javadoc/testAnnotationTypes/TestAnnotationTypes.java Wed Sep 18 17:13:26 2013 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2013, 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
@@ -23,20 +23,19 @@
/*
* @test
- * @bug 4973609
+ * @bug 4973609 8015249
* @summary Make sure that annotation types with 0 members does not have
* extra HR tags.
* @author jamieh
* @library ../lib/
- * @build JavadocTester
- * @build TestAnnotationTypes
+ * @build JavadocTester TestAnnotationTypes
* @run main TestAnnotationTypes
*/
public class TestAnnotationTypes extends JavadocTester {
//Test information.
- private static final String BUG_ID = "4973609";
+ private static final String BUG_ID = "4973609-8015249";
//Javadoc arguments.
private static final String[] ARGS = new String[] {
@@ -44,7 +43,31 @@
};
//Input for string search tests.
- private static final String[][] TEST = NO_TEST;
+ private static final String[][] TEST = {
+ {BUG_ID + FS + "pkg" + FS + "AnnotationTypeField.html",
+ "<li>Summary: </li>" + NL + "<li><a href=\"#annotation_type_" +
+ "field_summary\">Field</a> | </li>"},
+ {BUG_ID + FS + "pkg" + FS + "AnnotationTypeField.html",
+ "<li>Detail: </li>" + NL + "<li><a href=\"#annotation_type_" +
+ "field_detail\">Field</a> | </li>"},
+ {BUG_ID + FS + "pkg" + FS + "AnnotationTypeField.html",
+ "<!-- =========== ANNOTATION TYPE FIELD SUMMARY =========== -->"},
+ {BUG_ID + FS + "pkg" + FS + "AnnotationTypeField.html",
+ "<h3>Field Summary</h3>"},
+ {BUG_ID + FS + "pkg" + FS + "AnnotationTypeField.html",
+ "<td class=\"colLast\"><code><span class=\"strong\"><a href=\"../" +
+ "pkg/AnnotationTypeField.html#DEFAULT_NAME\">DEFAULT_NAME</a></span>" +
+ "</code> </td>"},
+ {BUG_ID + FS + "pkg" + FS + "AnnotationTypeField.html",
+ "<!-- ============ ANNOTATION TYPE FIELD DETAIL =========== -->"},
+ {BUG_ID + FS + "pkg" + FS + "AnnotationTypeField.html",
+ "<h4>DEFAULT_NAME</h4>" + NL + "<pre>public static final java." +
+ "lang.String DEFAULT_NAME</pre>"},
+ {BUG_ID + FS + "pkg" + FS + "AnnotationType.html",
+ "<li>Summary: </li>" + NL + "<li>Field | </li>"},
+ {BUG_ID + FS + "pkg" + FS + "AnnotationType.html",
+ "<li>Detail: </li>" + NL + "<li>Field | </li>"},
+ };
private static final String[][] NEGATED_TEST = {
{BUG_ID + FS + "pkg" + FS + "AnnotationType.html",
"<HR>" + NL + NL + "<P>" + NL + NL + "<P>" +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/langtools/test/com/sun/javadoc/testAnnotationTypes/pkg/AnnotationTypeField.java Wed Sep 18 17:13:26 2013 -0700
@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2013, 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 pkg;
+
+import java.lang.annotation.*;
+
+/**
+ * This is just a test for annotation type fields.
+ */
+@Documented public @interface AnnotationTypeField {
+ String DEFAULT_NAME = "test";
+
+ String name() default DEFAULT_NAME;
+}
--- a/langtools/test/com/sun/javadoc/testNewLanguageFeatures/TestNewLanguageFeatures.java Wed Sep 18 14:39:27 2013 +0200
+++ b/langtools/test/com/sun/javadoc/testNewLanguageFeatures/TestNewLanguageFeatures.java Wed Sep 18 17:13:26 2013 -0700
@@ -155,13 +155,13 @@
//=================================
//Make sure the summary links are correct.
{BUG_ID + FS + "pkg" + FS + "AnnotationType.html",
- "<li>Summary: </li>" + NL +
+ "<li>Summary: </li>" + NL + "<li>Field | </li>" + NL +
"<li><a href=\"#annotation_type_required_element_summary\">" +
"Required</a> | </li>" + NL + "<li>" +
"<a href=\"#annotation_type_optional_element_summary\">Optional</a></li>"},
//Make sure the detail links are correct.
{BUG_ID + FS + "pkg" + FS + "AnnotationType.html",
- "<li>Detail: </li>" + NL +
+ "<li>Detail: </li>" + NL + "<li>Field | </li>" + NL +
"<li><a href=\"#annotation_type_element_detail\">Element</a></li>"},
//Make sure the heading is correct.
{BUG_ID + FS + "pkg" + FS + "AnnotationType.html",