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