Tue, 14 May 2013 10:14:56 -0700
8012311: Cleanup names and duplicatre code in TagletManager
Reviewed-by: darcy
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 */
26 package com.sun.tools.doclets.formats.html;
28 import java.util.*;
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.*;
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;
52 private boolean printedOverallAnchor = false;
54 public HtmlSerialFieldWriter(SubWriterHolderWriter writer,
55 ClassDoc classdoc) {
56 super(writer, classdoc);
57 }
59 public List<FieldDoc> members(ClassDoc cd) {
60 return Arrays.asList(cd.serializableFields());
61 }
63 /**
64 * Return the header for serializable fields section.
65 *
66 * @return a content tree for the header
67 */
68 public Content getSerializableFieldsHeader() {
69 HtmlTree ul = new HtmlTree(HtmlTag.UL);
70 ul.addStyle(HtmlStyle.blockList);
71 return ul;
72 }
74 /**
75 * Return the header for serializable fields content section.
76 *
77 * @param isLastContent true if the cotent being documented is the last content.
78 * @return a content tree for the header
79 */
80 public Content getFieldsContentHeader(boolean isLastContent) {
81 HtmlTree li = new HtmlTree(HtmlTag.LI);
82 if (isLastContent)
83 li.addStyle(HtmlStyle.blockListLast);
84 else
85 li.addStyle(HtmlStyle.blockList);
86 return li;
87 }
89 /**
90 * Add serializable fields.
91 *
92 * @param heading the heading for the section
93 * @param serializableFieldsTree the tree to be added to the serializable fileds
94 * content tree
95 * @return a content tree for the serializable fields content
96 */
97 public Content getSerializableFields(String heading, Content serializableFieldsTree) {
98 HtmlTree li = new HtmlTree(HtmlTag.LI);
99 li.addStyle(HtmlStyle.blockList);
100 if (serializableFieldsTree.isValid()) {
101 if (!printedOverallAnchor) {
102 li.addContent(writer.getMarkerAnchor("serializedForm"));
103 printedOverallAnchor = true;
104 }
105 Content headingContent = new StringContent(heading);
106 Content serialHeading = HtmlTree.HEADING(HtmlConstants.SERIALIZED_MEMBER_HEADING,
107 headingContent);
108 li.addContent(serialHeading);
109 li.addContent(serializableFieldsTree);
110 }
111 return li;
112 }
114 /**
115 * Add the member header.
116 *
117 * @param fieldType the class document to be listed
118 * @param fieldTypeStr the string for the field type to be documented
119 * @param fieldDimensions the dimensions of the field string to be added
120 * @param fieldName name of the field to be added
121 * @param contentTree the content tree to which the member header will be added
122 */
123 public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,
124 String fieldDimensions, String fieldName, Content contentTree) {
125 Content nameContent = new RawHtml(fieldName);
126 Content heading = HtmlTree.HEADING(HtmlConstants.MEMBER_HEADING, nameContent);
127 contentTree.addContent(heading);
128 Content pre = new HtmlTree(HtmlTag.PRE);
129 if (fieldType == null) {
130 pre.addContent(fieldTypeStr);
131 } else {
132 Content fieldContent = writer.getLink(new LinkInfoImpl(
133 configuration, LinkInfoImpl.Kind.SERIAL_MEMBER, fieldType));
134 pre.addContent(fieldContent);
135 }
136 pre.addContent(fieldDimensions + " ");
137 pre.addContent(fieldName);
138 contentTree.addContent(pre);
139 }
141 /**
142 * Add the deprecated information for this member.
143 *
144 * @param field the field to document.
145 * @param contentTree the tree to which the deprecated info will be added
146 */
147 public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree) {
148 addDeprecatedInfo(field, contentTree);
149 }
151 /**
152 * Add the description text for this member.
153 *
154 * @param field the field to document.
155 * @param contentTree the tree to which the deprecated info will be added
156 */
157 public void addMemberDescription(FieldDoc field, Content contentTree) {
158 if (field.inlineTags().length > 0) {
159 writer.addInlineComment(field, contentTree);
160 }
161 Tag[] tags = field.tags("serial");
162 if (tags.length > 0) {
163 writer.addInlineComment(field, tags[0], contentTree);
164 }
165 }
167 /**
168 * Add the description text for this member represented by the tag.
169 *
170 * @param serialFieldTag the field to document (represented by tag)
171 * @param contentTree the tree to which the deprecated info will be added
172 */
173 public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree) {
174 String serialFieldTagDesc = serialFieldTag.description().trim();
175 if (!serialFieldTagDesc.isEmpty()) {
176 Content serialFieldContent = new RawHtml(serialFieldTagDesc);
177 Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent);
178 contentTree.addContent(div);
179 }
180 }
182 /**
183 * Add the tag information for this member.
184 *
185 * @param field the field to document.
186 * @param contentTree the tree to which the member tags info will be added
187 */
188 public void addMemberTags(FieldDoc field, Content contentTree) {
189 TagletOutputImpl output = new TagletOutputImpl();
190 TagletWriter.genTagOuput(configuration.tagletManager, field,
191 configuration.tagletManager.getCustomTaglets(field),
192 writer.getTagletWriterInstance(false), output);
193 Content tagContent = output.getContent();
194 Content dlTags = new HtmlTree(HtmlTag.DL);
195 dlTags.addContent(tagContent);
196 contentTree.addContent(dlTags); // TODO: what if empty?
197 }
199 /**
200 * Check to see if overview details should be printed. If
201 * nocomment option set or if there is no text to be printed
202 * for deprecation info, comment or tags, do not print overview details.
203 *
204 * @param field the field to check overview details for.
205 * @return true if overview details need to be printed
206 */
207 public boolean shouldPrintOverview(FieldDoc field) {
208 if (!configuration.nocomment) {
209 if(!field.commentText().isEmpty() ||
210 writer.hasSerializationOverviewTags(field))
211 return true;
212 }
213 if (field.tags("deprecated").length > 0)
214 return true;
215 return false;
216 }
217 }