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, typeElement, 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, memberSummaryTree, memberTree);
83 }
84
85 /**
86 * {@inheritDoc}
87 */
88 @Override
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
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
116 public Content getSignature(VariableElement field) {
117 return new MemberSignature(field)
118 .addType(field.asType())
119 .toContent();
120 }
121
122 /**
123 * {@inheritDoc}
124 */
125 @Override
126 public void addDeprecated(VariableElement field, Content fieldTree) {
127 addDeprecatedInfo(field, fieldTree);
128 }
129
130 /**
131 * {@inheritDoc}
132 */
133 @Override
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
144 public void addTags(VariableElement field, Content fieldTree) {
145 writer.addTagsInfo(field, fieldTree);
146 }
147
148 /**
149 * {@inheritDoc}
150 */
151 @Override
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
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 addSummaryAnchor(TypeElement typeElement, Content memberTree) {
201 memberTree.add(links.createAnchor(
202 SectionName.FIELD_SUMMARY));
203 }
204
205 /**
206 * {@inheritDoc}
207 */
208 @Override
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
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
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
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
264 protected void addSummaryType(Element member, Content tdSummaryType) {
265 addModifierAndType(member, member.asType(), tdSummaryType);
266 }
267
268 /**
269 * {@inheritDoc}
270 */
271 @Override
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
278 public Content getMemberTreeHeader(){
279 return writer.getMemberTreeHeader();
280 }
281 }