1 /*
2  * Copyright (c) 2013, 2018, 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.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package jdk.javadoc.internal.doclets.formats.html;
27 
28 import jdk.javadoc.internal.doclets.formats.html.markup.Table;
29 
30 import javax.lang.model.element.Element;
31 import javax.lang.model.element.ExecutableElement;
32 import javax.lang.model.element.TypeElement;
33 import javax.lang.model.type.TypeMirror;
34 
35 import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader;
36 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
40 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
41 import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeFieldWriter;
42 import jdk.javadoc.internal.doclets.toolkit.Content;
43 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter;
44 
45 /**
46  * Writes annotation type field documentation in HTML format.
47  *
48  *  <p><b>This is NOT part of any supported API.
49  *  If you write code that depends on this, you do so at your own risk.
50  *  This code and its internal interfaces are subject to change or
51  *  deletion without notice.</b>
52  *
53  * @author Bhavesh Patel
54  */
55 public class AnnotationTypeFieldWriterImpl extends AbstractMemberWriter
56     implements AnnotationTypeFieldWriter, MemberSummaryWriter {
57 
58     /**
59      * Construct a new AnnotationTypeFieldWriterImpl.
60      *
61      * @param writer         the writer that will write the output.
62      * @param annotationType the AnnotationType that holds this member.
63      */
AnnotationTypeFieldWriterImpl(SubWriterHolderWriter writer, TypeElement annotationType)64     public AnnotationTypeFieldWriterImpl(SubWriterHolderWriter writer,
65             TypeElement annotationType) {
66         super(writer, annotationType);
67     }
68 
69     /**
70      * {@inheritDoc}
71      */
getMemberSummaryHeader(TypeElement typeElement, Content memberSummaryTree)72     public Content getMemberSummaryHeader(TypeElement typeElement,
73             Content memberSummaryTree) {
74         memberSummaryTree.addContent(
75                 HtmlConstants.START_OF_ANNOTATION_TYPE_FIELD_SUMMARY);
76         Content memberTree = writer.getMemberTreeHeader();
77         writer.addSummaryHeader(this, typeElement, memberTree);
78         return memberTree;
79     }
80 
81     /**
82      * {@inheritDoc}
83      */
getMemberTreeHeader()84     public Content getMemberTreeHeader() {
85         return writer.getMemberTreeHeader();
86     }
87 
88     /**
89      * {@inheritDoc}
90      */
addMemberTree(Content memberSummaryTree, Content memberTree)91     public void addMemberTree(Content memberSummaryTree, Content memberTree) {
92         writer.addMemberTree(memberSummaryTree, memberTree);
93     }
94 
95     /**
96      * {@inheritDoc}
97      */
addAnnotationFieldDetailsMarker(Content memberDetails)98     public void addAnnotationFieldDetailsMarker(Content memberDetails) {
99         memberDetails.addContent(HtmlConstants.START_OF_ANNOTATION_TYPE_FIELD_DETAILS);
100     }
101 
102     /**
103      * {@inheritDoc}
104      */
addAnnotationDetailsTreeHeader(TypeElement typeElement, Content memberDetailsTree)105     public void addAnnotationDetailsTreeHeader(TypeElement typeElement,
106             Content memberDetailsTree) {
107         if (!writer.printedAnnotationFieldHeading) {
108             memberDetailsTree.addContent(links.createAnchor(
109                     SectionName.ANNOTATION_TYPE_FIELD_DETAIL));
110             Content heading = HtmlTree.HEADING(HtmlConstants.DETAILS_HEADING,
111                     contents.fieldDetailsLabel);
112             memberDetailsTree.addContent(heading);
113             writer.printedAnnotationFieldHeading = true;
114         }
115     }
116 
117     /**
118      * {@inheritDoc}
119      */
getAnnotationDocTreeHeader(Element member, Content annotationDetailsTree)120     public Content getAnnotationDocTreeHeader(Element member,
121             Content annotationDetailsTree) {
122         annotationDetailsTree.addContent(links.createAnchor(name(member)));
123         Content annotationDocTree = writer.getMemberTreeHeader();
124         Content heading = new HtmlTree(HtmlConstants.MEMBER_HEADING);
125         heading.addContent(name(member));
126         annotationDocTree.addContent(heading);
127         return annotationDocTree;
128     }
129 
130     /**
131      * {@inheritDoc}
132      */
getSignature(Element member)133     public Content getSignature(Element member) {
134         Content pre = new HtmlTree(HtmlTag.PRE);
135         writer.addAnnotationInfo(member, pre);
136         addModifiers(member, pre);
137         Content link =
138                 writer.getLink(new LinkInfoImpl(configuration,
139                         LinkInfoImpl.Kind.MEMBER, getType(member)));
140         pre.addContent(link);
141         pre.addContent(Contents.SPACE);
142         if (configuration.linksource) {
143             Content memberName = new StringContent(name(member));
144             writer.addSrcLink(member, memberName, pre);
145         } else {
146             addName(name(member), pre);
147         }
148         return pre;
149     }
150 
151     /**
152      * {@inheritDoc}
153      */
addDeprecated(Element member, Content annotationDocTree)154     public void addDeprecated(Element member, Content annotationDocTree) {
155         addDeprecatedInfo(member, annotationDocTree);
156     }
157 
158     /**
159      * {@inheritDoc}
160      */
addComments(Element member, Content annotationDocTree)161     public void addComments(Element member, Content annotationDocTree) {
162         addComment(member, annotationDocTree);
163     }
164 
165     /**
166      * {@inheritDoc}
167      */
addTags(Element member, Content annotationDocTree)168     public void addTags(Element member, Content annotationDocTree) {
169         writer.addTagsInfo(member, annotationDocTree);
170     }
171 
172     /**
173      * {@inheritDoc}
174      */
getAnnotationDetails(Content annotationDetailsTree)175     public Content getAnnotationDetails(Content annotationDetailsTree) {
176         if (configuration.allowTag(HtmlTag.SECTION)) {
177             HtmlTree htmlTree = HtmlTree.SECTION(getMemberTree(annotationDetailsTree));
178             return htmlTree;
179         }
180         return getMemberTree(annotationDetailsTree);
181     }
182 
183     /**
184      * {@inheritDoc}
185      */
getAnnotationDoc(Content annotationDocTree, boolean isLastContent)186     public Content getAnnotationDoc(Content annotationDocTree,
187             boolean isLastContent) {
188         return getMemberTree(annotationDocTree, isLastContent);
189     }
190 
191     /**
192      * {@inheritDoc}
193      */
addSummaryLabel(Content memberTree)194     public void addSummaryLabel(Content memberTree) {
195         Content label = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING,
196                 contents.fieldSummaryLabel);
197         memberTree.addContent(label);
198     }
199 
200     /**
201      * {@inheritDoc}
202      */
203     @Override
getSummaryTableHeader(Element member)204     public TableHeader getSummaryTableHeader(Element member) {
205         return new TableHeader(contents.modifierAndTypeLabel, contents.fields,
206                 contents.descriptionLabel);
207     }
208 
209     @Override
createSummaryTable()210     protected Table createSummaryTable() {
211         String summary = resources.getText("doclet.Member_Table_Summary",
212             resources.getText("doclet.Field_Summary"),
213             resources.getText("doclet.fields"));
214         Content caption = contents.getContent("doclet.Fields");
215 
216         TableHeader header = new TableHeader(contents.modifierAndTypeLabel, contents.fields,
217             contents.descriptionLabel);
218 
219         return new Table(configuration.htmlVersion, HtmlStyle.memberSummary)
220                 .setSummary(summary)
221                 .setCaption(caption)
222                 .setHeader(header)
223                 .setRowScopeColumn(1)
224                 .setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colSecond, HtmlStyle.colLast)
225                 .setUseTBody(false);  // temporary? compatibility mode for TBody
226     }
227 
228     /**
229      * {@inheritDoc}
230      */
231     @Override
addSummaryAnchor(TypeElement typeElement, Content memberTree)232     public void addSummaryAnchor(TypeElement typeElement, Content memberTree) {
233         memberTree.addContent(links.createAnchor(
234                 SectionName.ANNOTATION_TYPE_FIELD_SUMMARY));
235     }
236 
237     /**
238      * {@inheritDoc}
239      */
240     @Override
addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree)241     public void addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree) {
242     }
243 
244     /**
245      * {@inheritDoc}
246      */
247     @Override
addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree)248     public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) {
249     }
250 
251     /**
252      * {@inheritDoc}
253      */
254     @Override
addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, Content tdSummary)255     protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member,
256             Content tdSummary) {
257         Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
258                 writer.getDocLink(context, member, name(member), false));
259         Content code = HtmlTree.CODE(memberLink);
260         tdSummary.addContent(code);
261     }
262 
263     /**
264      * {@inheritDoc}
265      */
addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree)266     protected void addInheritedSummaryLink(TypeElement typeElement,
267             Element member, Content linksTree) {
268         //Not applicable.
269     }
270 
271     /**
272      * {@inheritDoc}
273      */
addSummaryType(Element member, Content tdSummaryType)274     protected void addSummaryType(Element member, Content tdSummaryType) {
275         addModifierAndType(member, getType(member), tdSummaryType);
276     }
277 
278     /**
279      * {@inheritDoc}
280      */
getDeprecatedLink(Element member)281     protected Content getDeprecatedLink(Element member) {
282         return writer.getDocLink(LinkInfoImpl.Kind.MEMBER,
283                 member, utils.getFullyQualifiedName(member));
284     }
285 
getType(Element member)286     private TypeMirror getType(Element member) {
287         if (utils.isConstructor(member))
288             return null;
289         if (utils.isExecutableElement(member))
290             return utils.getReturnType((ExecutableElement)member);
291         return member.asType();
292     }
293 }
294