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  * @author Robert Field
55  * @author Atul M Dambalkar
56  * @author Jamie Ho (rewrite)
57  * @author Bhavesh Patel (Modified)
58  */
59 public class FieldWriterImpl extends AbstractMemberWriter
60     implements FieldWriter, MemberSummaryWriter {
61 
FieldWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement)62     public FieldWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement) {
63         super(writer, typeElement);
64     }
65 
FieldWriterImpl(SubWriterHolderWriter writer)66     public FieldWriterImpl(SubWriterHolderWriter writer) {
67         super(writer);
68     }
69 
70     /**
71      * {@inheritDoc}
72      */
73     @Override
getMemberSummaryHeader(TypeElement typeElement, Content memberSummaryTree)74     public Content getMemberSummaryHeader(TypeElement typeElement,
75             Content memberSummaryTree) {
76         memberSummaryTree.add(MarkerComments.START_OF_FIELD_SUMMARY);
77         Content memberTree = new ContentBuilder();
78         writer.addSummaryHeader(this, typeElement, memberTree);
79         return memberTree;
80     }
81 
82     /**
83      * {@inheritDoc}
84      */
85     @Override
addMemberTree(Content memberSummaryTree, Content memberTree)86     public void addMemberTree(Content memberSummaryTree, Content memberTree) {
87         writer.addMemberTree(HtmlStyle.fieldSummary, memberSummaryTree, memberTree);
88     }
89 
90     /**
91      * {@inheritDoc}
92      */
93     @Override
getFieldDetailsTreeHeader(TypeElement typeElement, Content memberDetailsTree)94     public Content getFieldDetailsTreeHeader(TypeElement typeElement, Content memberDetailsTree) {
95         memberDetailsTree.add(MarkerComments.START_OF_FIELD_DETAILS);
96         Content fieldDetailsTree = new ContentBuilder();
97         Content heading = HtmlTree.HEADING(Headings.TypeDeclaration.DETAILS_HEADING,
98                 contents.fieldDetailsLabel);
99         fieldDetailsTree.add(links.createAnchor(
100                 SectionName.FIELD_DETAIL));
101         fieldDetailsTree.add(heading);
102         return fieldDetailsTree;
103     }
104 
105     /**
106      * {@inheritDoc}
107      */
108     @Override
getFieldDocTreeHeader(VariableElement field, Content fieldDetailsTree)109     public Content getFieldDocTreeHeader(VariableElement field, Content fieldDetailsTree) {
110         Content fieldTree = new ContentBuilder();
111         Content heading = new HtmlTree(Headings.TypeDeclaration.MEMBER_HEADING);
112         heading.add(links.createAnchor(name(field), new StringContent(name(field))));
113         fieldTree.add(heading);
114         return HtmlTree.SECTION(HtmlStyle.detail, fieldTree);
115     }
116 
117     /**
118      * {@inheritDoc}
119      */
120     @Override
getSignature(VariableElement field)121     public Content getSignature(VariableElement field) {
122         return new MemberSignature(field)
123                 .addType(field.asType())
124                 .toContent();
125     }
126 
127     /**
128      * {@inheritDoc}
129      */
130     @Override
addDeprecated(VariableElement field, Content fieldTree)131     public void addDeprecated(VariableElement field, Content fieldTree) {
132         addDeprecatedInfo(field, fieldTree);
133     }
134 
135     /**
136      * {@inheritDoc}
137      */
138     @Override
addComments(VariableElement field, Content fieldTree)139     public void addComments(VariableElement field, Content fieldTree) {
140         if (!utils.getFullBody(field).isEmpty()) {
141             writer.addInlineComment(field, fieldTree);
142         }
143     }
144 
145     /**
146      * {@inheritDoc}
147      */
148     @Override
addTags(VariableElement field, Content fieldTree)149     public void addTags(VariableElement field, Content fieldTree) {
150         writer.addTagsInfo(field, fieldTree);
151     }
152 
153     /**
154      * {@inheritDoc}
155      */
156     @Override
getFieldDetails(Content fieldDetailsTreeHeader, Content fieldDetailsTree)157     public Content getFieldDetails(Content fieldDetailsTreeHeader, Content fieldDetailsTree) {
158         Content fieldDetails = new ContentBuilder(fieldDetailsTreeHeader, fieldDetailsTree);
159         return getMemberTree(HtmlTree.SECTION(HtmlStyle.fieldDetails, fieldDetails));
160     }
161 
162     /**
163      * {@inheritDoc}
164      */
165     @Override
getFieldDoc(Content fieldTree)166     public Content getFieldDoc(Content fieldTree) {
167         return getMemberTree(fieldTree);
168     }
169 
170     /**
171      * {@inheritDoc}
172      */
173     @Override
addSummaryLabel(Content memberTree)174     public void addSummaryLabel(Content memberTree) {
175         Content label = HtmlTree.HEADING(Headings.TypeDeclaration.SUMMARY_HEADING,
176                 contents.fieldSummaryLabel);
177         memberTree.add(label);
178     }
179 
180     /**
181      * {@inheritDoc}
182      */
183     @Override
getSummaryTableHeader(Element member)184     public TableHeader getSummaryTableHeader(Element member) {
185         return new TableHeader(contents.modifierAndTypeLabel, contents.fieldLabel,
186                 contents.descriptionLabel);
187     }
188 
189     @Override
createSummaryTable()190     protected Table createSummaryTable() {
191         List<HtmlStyle> bodyRowStyles = Arrays.asList(HtmlStyle.colFirst, HtmlStyle.colSecond,
192                 HtmlStyle.colLast);
193 
194         return new Table(HtmlStyle.memberSummary)
195                 .setCaption(contents.fields)
196                 .setHeader(getSummaryTableHeader(typeElement))
197                 .setRowScopeColumn(1)
198                 .setColumnStyles(bodyRowStyles);
199     }
200 
201     /**
202      * {@inheritDoc}
203      */
204     @Override
addSummaryAnchor(TypeElement typeElement, Content memberTree)205     public void addSummaryAnchor(TypeElement typeElement, Content memberTree) {
206         memberTree.add(links.createAnchor(
207                 SectionName.FIELD_SUMMARY));
208     }
209 
210     /**
211      * {@inheritDoc}
212      */
213     @Override
addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree)214     public void addInheritedSummaryAnchor(TypeElement typeElement, Content inheritedTree) {
215         inheritedTree.add(links.createAnchor(
216                 SectionName.FIELDS_INHERITANCE, configuration.getClassName(typeElement)));
217     }
218 
219     /**
220      * {@inheritDoc}
221      */
222     @Override
addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree)223     public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) {
224         Content classLink = writer.getPreQualifiedClassLink(
225                 LinkInfoImpl.Kind.MEMBER, typeElement, false);
226         Content label;
227         if (configuration.summarizeOverriddenMethods) {
228             label = new StringContent(utils.isClass(typeElement)
229                     ? resources.getText("doclet.Fields_Declared_In_Class")
230                     : resources.getText("doclet.Fields_Declared_In_Interface"));
231         } else {
232             label = new StringContent(utils.isClass(typeElement)
233                     ? resources.getText("doclet.Fields_Inherited_From_Class")
234                     : resources.getText("doclet.Fields_Inherited_From_Interface"));
235         }
236         Content labelHeading = HtmlTree.HEADING(Headings.TypeDeclaration.INHERITED_SUMMARY_HEADING,
237                 label);
238         labelHeading.add(Entity.NO_BREAK_SPACE);
239         labelHeading.add(classLink);
240         inheritedTree.add(labelHeading);
241     }
242 
243     /**
244      * {@inheritDoc}
245      */
246     @Override
addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member, Content tdSummary)247     protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member,
248             Content tdSummary) {
249         Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
250                 writer.getDocLink(context, typeElement , member, name(member), false));
251         Content code = HtmlTree.CODE(memberLink);
252         tdSummary.add(code);
253     }
254 
255     /**
256      * {@inheritDoc}
257      */
258     @Override
addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree)259     protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree) {
260         linksTree.add(
261                 writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member,
262                 name(member), false));
263     }
264 
265     /**
266      * {@inheritDoc}
267      */
268     @Override
addSummaryType(Element member, Content tdSummaryType)269     protected void addSummaryType(Element member, Content tdSummaryType) {
270         addModifierAndType(member, member.asType(), tdSummaryType);
271     }
272 
273     /**
274      * {@inheritDoc}
275      */
276     @Override
getDeprecatedLink(Element member)277     protected Content getDeprecatedLink(Element member) {
278         String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName();
279         return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name);
280     }
281 
282     @Override
getMemberTreeHeader()283     public Content getMemberTreeHeader(){
284         return writer.getMemberTreeHeader();
285     }
286 }
287