1 /*
2  * Copyright (c) 1997, 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 import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader;
30 
31 import java.util.Arrays;
32 import java.util.List;
33 
34 import javax.lang.model.element.Element;
35 import javax.lang.model.element.TypeElement;
36 import javax.lang.model.element.VariableElement;
37 
38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
40 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
41 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
42 import jdk.javadoc.internal.doclets.formats.html.markup.Navigation;
43 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
44 import jdk.javadoc.internal.doclets.toolkit.Content;
45 import jdk.javadoc.internal.doclets.toolkit.FieldWriter;
46 import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter;
47 
48 /**
49  * Writes field documentation in HTML format.
50  *
51  *  <p><b>This is NOT part of any supported API.
52  *  If you write code that depends on this, you do so at your own risk.
53  *  This code and its internal interfaces are subject to change or
54  *  deletion without notice.</b>
55  *
56  * @author Robert Field
57  * @author Atul M Dambalkar
58  * @author Jamie Ho (rewrite)
59  * @author Bhavesh Patel (Modified)
60  */
61 public class FieldWriterImpl extends AbstractMemberWriter
62     implements FieldWriter, MemberSummaryWriter {
63 
FieldWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement)64     public FieldWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement) {
65         super(writer, typeElement);
66     }
67 
FieldWriterImpl(SubWriterHolderWriter writer)68     public FieldWriterImpl(SubWriterHolderWriter writer) {
69         super(writer);
70     }
71 
72     /**
73      * {@inheritDoc}
74      */
75     @Override
getMemberSummaryHeader(TypeElement typeElement, Content memberSummaryTree)76     public Content getMemberSummaryHeader(TypeElement typeElement,
77             Content memberSummaryTree) {
78         memberSummaryTree.addContent(HtmlConstants.START_OF_FIELD_SUMMARY);
79         Content memberTree = writer.getMemberTreeHeader();
80         writer.addSummaryHeader(this, typeElement, memberTree);
81         return memberTree;
82     }
83 
84     /**
85      * {@inheritDoc}
86      */
87     @Override
addMemberTree(Content memberSummaryTree, Content memberTree)88     public void addMemberTree(Content memberSummaryTree, Content memberTree) {
89         writer.addMemberTree(memberSummaryTree, memberTree);
90     }
91 
92     /**
93      * {@inheritDoc}
94      */
95     @Override
getFieldDetailsTreeHeader(TypeElement typeElement, Content memberDetailsTree)96     public Content getFieldDetailsTreeHeader(TypeElement typeElement, Content memberDetailsTree) {
97         memberDetailsTree.addContent(HtmlConstants.START_OF_FIELD_DETAILS);
98         Content fieldDetailsTree = writer.getMemberTreeHeader();
99         fieldDetailsTree.addContent(links.createAnchor(
100                 SectionName.FIELD_DETAIL));
101         Content heading = HtmlTree.HEADING(HtmlConstants.DETAILS_HEADING,
102                 contents.fieldDetailsLabel);
103         fieldDetailsTree.addContent(heading);
104         return fieldDetailsTree;
105     }
106 
107     /**
108      * {@inheritDoc}
109      */
110     @Override
getFieldDocTreeHeader(VariableElement field, Content fieldDetailsTree)111     public Content getFieldDocTreeHeader(VariableElement field, Content fieldDetailsTree) {
112         fieldDetailsTree.addContent(links.createAnchor(name(field)));
113         Content fieldTree = writer.getMemberTreeHeader();
114         Content heading = new HtmlTree(HtmlConstants.MEMBER_HEADING);
115         heading.addContent(name(field));
116         fieldTree.addContent(heading);
117         return fieldTree;
118     }
119 
120     /**
121      * {@inheritDoc}
122      */
123     @Override
getSignature(VariableElement field)124     public Content getSignature(VariableElement field) {
125         Content pre = new HtmlTree(HtmlTag.PRE);
126         writer.addAnnotationInfo(field, pre);
127         addModifiers(field, pre);
128         Content fieldlink = writer.getLink(new LinkInfoImpl(
129                 configuration, LinkInfoImpl.Kind.MEMBER, field.asType()));
130         pre.addContent(fieldlink);
131         pre.addContent(" ");
132         if (configuration.linksource) {
133             Content fieldName = new StringContent(name(field));
134             writer.addSrcLink(field, fieldName, pre);
135         } else {
136             addName(name(field), pre);
137         }
138         return pre;
139     }
140 
141     /**
142      * {@inheritDoc}
143      */
144     @Override
addDeprecated(VariableElement field, Content fieldTree)145     public void addDeprecated(VariableElement field, Content fieldTree) {
146         addDeprecatedInfo(field, fieldTree);
147     }
148 
149     /**
150      * {@inheritDoc}
151      */
152     @Override
addComments(VariableElement field, Content fieldTree)153     public void addComments(VariableElement field, Content fieldTree) {
154         if (!utils.getFullBody(field).isEmpty()) {
155             writer.addInlineComment(field, fieldTree);
156         }
157     }
158 
159     /**
160      * {@inheritDoc}
161      */
162     @Override
addTags(VariableElement field, Content fieldTree)163     public void addTags(VariableElement field, Content fieldTree) {
164         writer.addTagsInfo(field, fieldTree);
165     }
166 
167     /**
168      * {@inheritDoc}
169      */
170     @Override
getFieldDetails(Content fieldDetailsTree)171     public Content getFieldDetails(Content fieldDetailsTree) {
172         if (configuration.allowTag(HtmlTag.SECTION)) {
173             HtmlTree htmlTree = HtmlTree.SECTION(getMemberTree(fieldDetailsTree));
174             return htmlTree;
175         }
176         return getMemberTree(fieldDetailsTree);
177     }
178 
179     /**
180      * {@inheritDoc}
181      */
182     @Override
getFieldDoc(Content fieldTree, boolean isLastContent)183     public Content getFieldDoc(Content fieldTree,
184             boolean isLastContent) {
185         return getMemberTree(fieldTree, isLastContent);
186     }
187 
188     /**
189      * {@inheritDoc}
190      */
191     @Override
addSummaryLabel(Content memberTree)192     public void addSummaryLabel(Content memberTree) {
193         Content label = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING,
194                 contents.fieldSummaryLabel);
195         memberTree.addContent(label);
196     }
197 
198     /**
199      * {@inheritDoc}
200      */
201     @Override
getSummaryTableHeader(Element member)202     public TableHeader getSummaryTableHeader(Element member) {
203         return new TableHeader(contents.modifierAndTypeLabel, contents.fieldLabel,
204                 contents.descriptionLabel);
205     }
206 
207     @Override
createSummaryTable()208     protected Table createSummaryTable() {
209         String summary =  resources.getText("doclet.Member_Table_Summary",
210                 resources.getText("doclet.Field_Summary"),
211                 resources.getText("doclet.fields"));
212 
213         List<HtmlStyle> bodyRowStyles = Arrays.asList(HtmlStyle.colFirst, HtmlStyle.colSecond,
214                 HtmlStyle.colLast);
215 
216         return new Table(configuration.htmlVersion, HtmlStyle.memberSummary)
217                 .setSummary(summary)
218                 .setCaption(contents.fields)
219                 .setHeader(getSummaryTableHeader(typeElement))
220                 .setRowScopeColumn(1)
221                 .setColumnStyles(bodyRowStyles)
222                 .setUseTBody(false);  // temporary? compatibility mode for TBody
223     }
224 
225     /**
226      * {@inheritDoc}
227      */
228     @Override
addSummaryAnchor(TypeElement typeElement, Content memberTree)229     public void addSummaryAnchor(TypeElement typeElement, Content memberTree) {
230         memberTree.addContent(links.createAnchor(
231                 SectionName.FIELD_SUMMARY));
232     }
233 
234     /**
235      * {@inheritDoc}
236      */
237     @Override
addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree)238     public void addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree) {
239         inheritedTree.addContent(links.createAnchor(
240                 SectionName.FIELDS_INHERITANCE, configuration.getClassName(typeElement)));
241     }
242 
243     /**
244      * {@inheritDoc}
245      */
246     @Override
addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree)247     public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) {
248         Content classLink = writer.getPreQualifiedClassLink(
249                 LinkInfoImpl.Kind.MEMBER, typeElement, false);
250         Content label;
251         if (configuration.summarizeOverriddenMethods) {
252             label = new StringContent(utils.isClass(typeElement)
253                     ? configuration.getText("doclet.Fields_Declared_In_Class")
254                     : configuration.getText("doclet.Fields_Declared_In_Interface"));
255         } else {
256             label = new StringContent(utils.isClass(typeElement)
257                     ? configuration.getText("doclet.Fields_Inherited_From_Class")
258                     : configuration.getText("doclet.Fields_Inherited_From_Interface"));
259         }
260         Content labelHeading = HtmlTree.HEADING(HtmlConstants.INHERITED_SUMMARY_HEADING,
261                 label);
262         labelHeading.addContent(Contents.SPACE);
263         labelHeading.addContent(classLink);
264         inheritedTree.addContent(labelHeading);
265     }
266 
267     /**
268      * {@inheritDoc}
269      */
270     @Override
addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, Content tdSummary)271     protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member,
272             Content tdSummary) {
273         Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
274                 writer.getDocLink(context, typeElement , member, name(member), false));
275         Content code = HtmlTree.CODE(memberLink);
276         tdSummary.addContent(code);
277     }
278 
279     /**
280      * {@inheritDoc}
281      */
282     @Override
addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree)283     protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree) {
284         linksTree.addContent(
285                 writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member,
286                 name(member), false));
287     }
288 
289     /**
290      * {@inheritDoc}
291      */
292     @Override
addSummaryType(Element member, Content tdSummaryType)293     protected void addSummaryType(Element member, Content tdSummaryType) {
294         addModifierAndType(member, member.asType(), tdSummaryType);
295     }
296 
297     /**
298      * {@inheritDoc}
299      */
300     @Override
getDeprecatedLink(Element member)301     protected Content getDeprecatedLink(Element member) {
302         String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName();
303         return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name);
304     }
305 }
306