1 /*
2 * Copyright (c) 1998, 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.*;
29
30 import javax.lang.model.element.TypeElement;
31 import javax.lang.model.element.VariableElement;
32 import javax.lang.model.type.TypeMirror;
33
34 import com.sun.source.doctree.DocTree;
35
36 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
37 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
38 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
39 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
40 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
41 import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
42 import jdk.javadoc.internal.doclets.toolkit.Content;
43 import jdk.javadoc.internal.doclets.toolkit.SerializedFormWriter;
44 import jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter;
45 import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
46
47 /**
48 * Generate serialized form for serializable fields.
49 * Documentation denoted by the tags <code>serial</code> and
50 * <code>serialField</code> is processed.
51 *
52 * <p><b>This is NOT part of any supported API.
53 * If you write code that depends on this, you do so at your own risk.
54 * This code and its internal interfaces are subject to change or
55 * deletion without notice.</b>
56 */
57 public class HtmlSerialFieldWriter extends FieldWriterImpl
58 implements SerializedFormWriter.SerialFieldWriter {
59
60 public HtmlSerialFieldWriter(SubWriterHolderWriter writer, TypeElement typeElement) {
61 super(writer, typeElement);
62 }
63
64 public SortedSet<VariableElement> members(TypeElement te) {
65 return utils.serializableFields(te);
66 }
67
68 /**
69 * Return the header for serializable fields section.
70 *
71 * @return a content tree for the header
72 */
73 public Content getSerializableFieldsHeader() {
74 HtmlTree ul = new HtmlTree(HtmlTag.UL);
75 ul.setStyle(HtmlStyle.blockList);
76 return ul;
77 }
78
79 /**
80 * Return the header for serializable fields content section.
81 *
82 * @param isLastContent true if the content being documented is the last content.
83 * @return a content tree for the header
84 */
85 public Content getFieldsContentHeader(boolean isLastContent) {
86 HtmlTree li = new HtmlTree(HtmlTag.LI);
87 li.setStyle(HtmlStyle.blockList);
88 return li;
89 }
90
91 /**
92 * Add serializable fields.
93 *
94 * @param heading the heading for the section
95 * @param serializableFieldsTree the tree to be added to the serializable fields
96 * content tree
97 * @return a content tree for the serializable fields content
98 */
99 public Content getSerializableFields(String heading, Content serializableFieldsTree) {
100 HtmlTree section = HtmlTree.SECTION(HtmlStyle.detail);
101 if (serializableFieldsTree.isValid()) {
102 Content headingContent = new StringContent(heading);
103 Content serialHeading = HtmlTree.HEADING(Headings.SerializedForm.CLASS_SUBHEADING, headingContent);
104 section.add(serialHeading);
105 section.add(serializableFieldsTree);
106 }
107 return HtmlTree.LI(HtmlStyle.blockList, section);
108 }
109
110 @Override
111 public void addMemberHeader(TypeElement fieldType, String fieldTypeStr,
112 String fieldDimensions, String fieldName, Content contentTree) {
113 Content nameContent = new StringContent(fieldName);
114 Content heading = HtmlTree.HEADING(Headings.SerializedForm.MEMBER_HEADING, nameContent);
115 contentTree.add(heading);
116 Content pre = new HtmlTree(HtmlTag.PRE);
117 if (fieldType == null) {
118 pre.add(fieldTypeStr);
119 } else {
120 Content fieldContent = writer.getLink(new LinkInfoImpl(
121 configuration, LinkInfoImpl.Kind.SERIAL_MEMBER, fieldType));
122 pre.add(fieldContent);
123 }
124 pre.add(fieldDimensions + " ");
125 pre.add(fieldName);
126 contentTree.add(pre);
127 }
128
129 @Override
130 public void addMemberHeader(TypeMirror fieldType, String fieldName, Content contentTree) {
131 Content nameContent = new StringContent(fieldName);
132 Content heading = HtmlTree.HEADING(HtmlTag.H5, nameContent);
133 contentTree.add(heading);
134 Content pre = new HtmlTree(HtmlTag.PRE);
135 Content fieldContent = writer.getLink(new LinkInfoImpl(
136 configuration, LinkInfoImpl.Kind.SERIAL_MEMBER, fieldType));
137 pre.add(fieldContent);
138 pre.add(" ");
139 pre.add(fieldName);
140 contentTree.add(pre);
141 }
142
143 /**
144 * Add the deprecated information for this member.
145 *
146 * @param field the field to document.
147 * @param contentTree the tree to which the deprecated info will be added
148 */
149 public void addMemberDeprecatedInfo(VariableElement field, Content contentTree) {
150 addDeprecatedInfo(field, contentTree);
151 }
152
153 /**
154 * Add the description text for this member.
155 *
156 * @param field the field to document.
157 * @param contentTree the tree to which the deprecated info will be added
158 */
159 public void addMemberDescription(VariableElement field, Content contentTree) {
160 if (!utils.getFullBody(field).isEmpty()) {
161 writer.addInlineComment(field, contentTree);
162 }
163 List<? extends DocTree> tags = utils.getBlockTags(field, DocTree.Kind.SERIAL);
164 if (!tags.isEmpty()) {
165 writer.addInlineComment(field, tags.get(0), contentTree);
166 }
167 }
168
169 /**
170 * Add the description text for this member represented by the tag.
171 *
172 * @param serialFieldTag the field to document (represented by tag)
173 * @param contentTree the tree to which the deprecated info will be added
174 */
175 public void addMemberDescription(VariableElement field, DocTree serialFieldTag, Content contentTree) {
176 CommentHelper ch = utils.getCommentHelper(field);
177 List<? extends DocTree> description = ch.getDescription(configuration, serialFieldTag);
178 if (!description.isEmpty()) {
179 Content serialFieldContent = new RawHtml(ch.getText(description));
180 Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent);
181 contentTree.add(div);
182 }
183 }
184
185 /**
186 * Add the tag information for this member.
187 *
188 * @param field the field to document.
189 * @param contentTree the tree to which the member tags info will be added
190 */
191 public void addMemberTags(VariableElement field, Content contentTree) {
192 Content tagContent = new ContentBuilder();
193 TagletWriter.genTagOutput(configuration.tagletManager, field,
194 configuration.tagletManager.getBlockTaglets(field),
195 writer.getTagletWriterInstance(false), tagContent);
196 Content dlTags = new HtmlTree(HtmlTag.DL);
197 dlTags.add(tagContent);
198 contentTree.add(dlTags); // TODO: what if empty?
199 }
200
201 /**
202 * Check to see if overview details should be printed. If
203 * nocomment option set or if there is no text to be printed
204 * for deprecation info, comment or tags, do not print overview details.
205 *
206 * @param field the field to check overview details for.
207 * @return true if overview details need to be printed
208 */
209 public boolean shouldPrintOverview(VariableElement field) {
210 if (!options.noComment) {
211 if(!utils.getFullBody(field).isEmpty() ||
212 writer.hasSerializationOverviewTags(field))
213 return true;
214 }
215 if (utils.isDeprecated(field))
216 return true;
217 return false;
218 }
219 }