Thu, 13 Jan 2011 21:28:38 -0800
7010528: javadoc performance regression
Reviewed-by: jjg
1 /*
2 * Copyright (c) 1998, 2010, 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.internal.toolkit.*;
32 import com.sun.tools.doclets.internal.toolkit.taglets.*;
33 import com.sun.tools.doclets.internal.toolkit.util.*;
34 import com.sun.tools.doclets.formats.html.markup.*;
36 /**
37 * Generate serialized form for serializable fields.
38 * Documentation denoted by the tags <code>serial</code> and
39 * <code>serialField</code> is processed.
40 *
41 * @author Joe Fialli
42 * @author Bhavesh Patel (Modified)
43 */
44 public class HtmlSerialFieldWriter extends FieldWriterImpl
45 implements SerializedFormWriter.SerialFieldWriter {
46 ProgramElementDoc[] members = null;
48 private boolean printedOverallAnchor = false;
50 public HtmlSerialFieldWriter(SubWriterHolderWriter writer,
51 ClassDoc classdoc) {
52 super(writer, classdoc);
53 }
55 public List<FieldDoc> members(ClassDoc cd) {
56 return Util.asList(cd.serializableFields());
57 }
59 protected void printTypeLinkNoDimension(Type type) {
60 ClassDoc cd = type.asClassDoc();
61 //Linking to package private classes in serialized for causes
62 //broken links. Don't link to them.
63 if (type.isPrimitive() || cd.isPackagePrivate()) {
64 print(type.typeName());
65 } else {
66 writer.printLink(new LinkInfoImpl(
67 LinkInfoImpl.CONTEXT_SERIAL_MEMBER, type));
68 }
69 }
71 /**
72 * Return the header for serializable fields section.
73 *
74 * @return a content tree for the header
75 */
76 public Content getSerializableFieldsHeader() {
77 HtmlTree ul = new HtmlTree(HtmlTag.UL);
78 ul.addStyle(HtmlStyle.blockList);
79 return ul;
80 }
82 /**
83 * Return the header for serializable fields content section.
84 *
85 * @param isLastContent true if the cotent being documented is the last content.
86 * @return a content tree for the header
87 */
88 public Content getFieldsContentHeader(boolean isLastContent) {
89 HtmlTree li = new HtmlTree(HtmlTag.LI);
90 if (isLastContent)
91 li.addStyle(HtmlStyle.blockListLast);
92 else
93 li.addStyle(HtmlStyle.blockList);
94 return li;
95 }
97 /**
98 * Add serializable fields.
99 *
100 * @param heading the heading for the section
101 * @param serializableFieldsTree the tree to be added to the serializable fileds
102 * content tree
103 * @return a content tree for the serializable fields content
104 */
105 public Content getSerializableFields(String heading, Content serializableFieldsTree) {
106 HtmlTree li = new HtmlTree(HtmlTag.LI);
107 li.addStyle(HtmlStyle.blockList);
108 if (serializableFieldsTree.isValid()) {
109 if (!printedOverallAnchor) {
110 li.addContent(writer.getMarkerAnchor("serializedForm"));
111 printedOverallAnchor = true;
112 }
113 Content headingContent = new StringContent(heading);
114 Content serialHeading = HtmlTree.HEADING(HtmlConstants.SERIALIZED_MEMBER_HEADING,
115 headingContent);
116 li.addContent(serialHeading);
117 li.addContent(serializableFieldsTree);
118 }
119 return li;
120 }
122 /**
123 * Add the member header.
124 *
125 * @param fieldsType the class document to be listed
126 * @param fieldTypeStr the string for the filed type to be documented
127 * @param fieldDimensions the dimensions of the field string to be added
128 * @param firldName name of the field to be added
129 * @param contentTree the content tree to which the member header will be added
130 */
131 public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,
132 String fieldDimensions, String fieldName, Content contentTree) {
133 Content nameContent = new RawHtml(fieldName);
134 Content heading = HtmlTree.HEADING(HtmlConstants.MEMBER_HEADING, nameContent);
135 contentTree.addContent(heading);
136 Content pre = new HtmlTree(HtmlTag.PRE);
137 if (fieldType == null) {
138 pre.addContent(fieldTypeStr);
139 } else {
140 Content fieldContent = new RawHtml(writer.getLink(new LinkInfoImpl(
141 LinkInfoImpl.CONTEXT_SERIAL_MEMBER, fieldType)));
142 pre.addContent(fieldContent);
143 }
144 pre.addContent(fieldDimensions + " ");
145 pre.addContent(fieldName);
146 contentTree.addContent(pre);
147 }
149 /**
150 * Add the deprecated information for this member.
151 *
152 * @param field the field to document.
153 * @param contentTree the tree to which the deprecated info will be added
154 */
155 public void addMemberDeprecatedInfo(FieldDoc field, Content contentTree) {
156 addDeprecatedInfo(field, contentTree);
157 }
159 /**
160 * Add the description text for this member.
161 *
162 * @param field the field to document.
163 * @param contentTree the tree to which the deprecated info will be added
164 */
165 public void addMemberDescription(FieldDoc field, Content contentTree) {
166 if (field.inlineTags().length > 0) {
167 writer.addInlineComment(field, contentTree);
168 }
169 Tag[] tags = field.tags("serial");
170 if (tags.length > 0) {
171 writer.addInlineComment(field, tags[0], contentTree);
172 }
173 }
175 /**
176 * Add the description text for this member represented by the tag.
177 *
178 * @param serialFieldTag the field to document (represented by tag)
179 * @param contentTree the tree to which the deprecated info will be added
180 */
181 public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree) {
182 String serialFieldTagDesc = serialFieldTag.description().trim();
183 if (!serialFieldTagDesc.isEmpty()) {
184 Content serialFieldContent = new RawHtml(serialFieldTagDesc);
185 Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent);
186 contentTree.addContent(div);
187 }
188 }
190 /**
191 * Add the tag information for this member.
192 *
193 * @param field the field to document.
194 * @param contentTree the tree to which the member tags info will be added
195 */
196 public void addMemberTags(FieldDoc field, Content contentTree) {
197 TagletOutputImpl output = new TagletOutputImpl("");
198 TagletWriter.genTagOuput(configuration().tagletManager, field,
199 configuration().tagletManager.getCustomTags(field),
200 writer.getTagletWriterInstance(false), output);
201 String outputString = output.toString().trim();
202 Content dlTags = new HtmlTree(HtmlTag.DL);
203 if (!outputString.isEmpty()) {
204 Content tagContent = new RawHtml(outputString);
205 dlTags.addContent(tagContent);
206 }
207 contentTree.addContent(dlTags);
208 }
210 /**
211 * Check to see if overview details should be printed. If
212 * nocomment option set or if there is no text to be printed
213 * for deprecation info, comment or tags, do not print overview details.
214 *
215 * @param field the field to check overview details for.
216 * @return true if overview details need to be printed
217 */
218 public boolean shouldPrintOverview(FieldDoc field) {
219 if (!configuration().nocomment) {
220 if(!field.commentText().isEmpty() ||
221 writer.hasSerializationOverviewTags(field))
222 return true;
223 }
224 if (field.tags("deprecated").length > 0)
225 return true;
226 return false;
227 }
228 }