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