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
57 public FieldWriterImpl(SubWriterHolderWriter writer, TypeElement typeElement) {
58 super(writer, typeElement);
59 }
60
61 public FieldWriterImpl(SubWriterHolderWriter writer) {
62 super(writer);
63 }
64
65 /**
66 * {@inheritDoc}
67 */
68 @Override
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, memberTree);
74 return memberTree;
75 }
76
77 /**
78 * {@inheritDoc}
79 */
80 @Override
81 public void addMemberTree(Content memberSummaryTree, Content memberTree) {
82 writer.addMemberTree(HtmlStyle.fieldSummary,
83 SectionName.FIELD_SUMMARY, memberSummaryTree, memberTree);
84 }
85
86 /**
87 * {@inheritDoc}
88 */
89 @Override
90 public Content getFieldDetailsTreeHeader(Content memberDetailsTree) {
91 memberDetailsTree.add(MarkerComments.START_OF_FIELD_DETAILS);
92 Content fieldDetailsTree = new ContentBuilder();
93 Content heading = HtmlTree.HEADING(Headings.TypeDeclaration.DETAILS_HEADING,
94 contents.fieldDetailsLabel);
95 fieldDetailsTree.add(heading);
96 return fieldDetailsTree;
97 }
98
99 /**
100 * {@inheritDoc}
101 */
102 @Override
103 public Content getFieldDocTreeHeader(VariableElement field) {
104 Content fieldTree = new ContentBuilder();
105 Content heading = new HtmlTree(Headings.TypeDeclaration.MEMBER_HEADING,
106 new StringContent(name(field)));
107 fieldTree.add(heading);
108 return HtmlTree.SECTION(HtmlStyle.detail, fieldTree).setId(name(field));
109 }
110
111 /**
112 * {@inheritDoc}
113 */
114 @Override
115 public Content getSignature(VariableElement field) {
116 return new MemberSignature(field)
117 .addType(utils.asInstantiatedFieldType(typeElement, field))
118 .toContent();
119 }
120
121 /**
122 * {@inheritDoc}
123 */
124 @Override
125 public void addDeprecated(VariableElement field, Content fieldTree) {
126 addDeprecatedInfo(field, fieldTree);
127 }
128
129 /**
130 * {@inheritDoc}
131 */
132 @Override
133 public void addComments(VariableElement field, Content fieldTree) {
134 if (!utils.getFullBody(field).isEmpty()) {
135 writer.addInlineComment(field, fieldTree);
136 }
137 }
138
139 /**
140 * {@inheritDoc}
141 */
142 @Override
143 public void addTags(VariableElement field, Content fieldTree) {
144 writer.addTagsInfo(field, fieldTree);
145 }
146
147 /**
148 * {@inheritDoc}
149 */
150 @Override
151 public Content getFieldDetails(Content fieldDetailsTreeHeader, Content fieldDetailsTree) {
152 Content fieldDetails = new ContentBuilder(fieldDetailsTreeHeader, fieldDetailsTree);
153 return getMemberTree(HtmlTree.SECTION(HtmlStyle.fieldDetails, fieldDetails)
154 .setId(SectionName.FIELD_DETAIL.getName()));
155 }
156
157 /**
158 * {@inheritDoc}
159 */
160 @Override
161 public Content getFieldDoc(Content fieldTree) {
162 return getMemberTree(fieldTree);
163 }
164
165 /**
166 * {@inheritDoc}
167 */
168 @Override
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
179 public TableHeader getSummaryTableHeader(Element member) {
180 return new TableHeader(contents.modifierAndTypeLabel, contents.fieldLabel,
181 contents.descriptionLabel);
182 }
183
184 @Override
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
200 public void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree) {
201 Content classLink = writer.getPreQualifiedClassLink(
202 LinkInfoImpl.Kind.MEMBER, typeElement, false);
203 Content label;
204 if (options.summarizeOverriddenMethods) {
205 label = new StringContent(utils.isClass(typeElement)
206 ? resources.getText("doclet.Fields_Declared_In_Class")
207 : resources.getText("doclet.Fields_Declared_In_Interface"));
208 } else {
209 label = new StringContent(utils.isClass(typeElement)
210 ? resources.getText("doclet.Fields_Inherited_From_Class")
211 : resources.getText("doclet.Fields_Inherited_From_Interface"));
212 }
213 HtmlTree labelHeading = HtmlTree.HEADING(Headings.TypeDeclaration.INHERITED_SUMMARY_HEADING,
214 label);
215 labelHeading.setId(SectionName.FIELDS_INHERITANCE.getName()
216 + links.getName(configuration.getClassName(typeElement)));
217 labelHeading.add(Entity.NO_BREAK_SPACE);
218 labelHeading.add(classLink);
219 inheritedTree.add(labelHeading);
220 }
221
222 /**
223 * {@inheritDoc}
224 */
225 @Override
226 protected void addSummaryLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element member,
227 Content tdSummary) {
228 Content memberLink = HtmlTree.SPAN(HtmlStyle.memberNameLink,
229 writer.getDocLink(context, typeElement , member, name(member), false));
230 Content code = HtmlTree.CODE(memberLink);
231 tdSummary.add(code);
232 }
233
234 /**
235 * {@inheritDoc}
236 */
237 @Override
238 protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content linksTree) {
239 linksTree.add(
240 writer.getDocLink(LinkInfoImpl.Kind.MEMBER, typeElement, member,
241 name(member), false));
242 }
243
244 /**
245 * {@inheritDoc}
246 */
247 @Override
248 protected void addSummaryType(Element member, Content tdSummaryType) {
249 addModifierAndType(member, utils.asInstantiatedFieldType(typeElement, (VariableElement)member), tdSummaryType);
250 }
251
252 /**
253 * {@inheritDoc}
254 */
255 @Override
256 protected Content getDeprecatedLink(Element member) {
257 String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName();
258 return writer.getDocLink(LinkInfoImpl.Kind.MEMBER, member, name);
259 }
260
261 @Override
262 public Content getMemberTreeHeader(){
263 return writer.getMemberTreeHeader();
264 }
265 }