Wed, 10 Oct 2012 16:48:21 -0700
8000665: fix "internal API" comments on javadoc files
Reviewed-by: darcy
1 /*
2 * Copyright (c) 1998, 2012, 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 protected void printTypeLinkNoDimension(Type type) {
64 ClassDoc cd = type.asClassDoc();
65 //Linking to package private classes in serialized for causes
66 //broken links. Don't link to them.
67 if (type.isPrimitive() || cd.isPackagePrivate()) {
68 print(type.typeName());
69 } else {
70 writer.printLink(new LinkInfoImpl(
71 LinkInfoImpl.CONTEXT_SERIAL_MEMBER, type));
72 }
73 }
75 /**
76 * Return the header for serializable fields section.
77 *
78 * @return a content tree for the header
79 */
80 public Content getSerializableFieldsHeader() {
81 HtmlTree ul = new HtmlTree(HtmlTag.UL);
82 ul.addStyle(HtmlStyle.blockList);
83 return ul;
84 }
86 /**
87 * Return the header for serializable fields content section.
88 *
89 * @param isLastContent true if the cotent being documented is the last content.
90 * @return a content tree for the header
91 */
92 public Content getFieldsContentHeader(boolean isLastContent) {
93 HtmlTree li = new HtmlTree(HtmlTag.LI);
94 if (isLastContent)
95 li.addStyle(HtmlStyle.blockListLast);
96 else
97 li.addStyle(HtmlStyle.blockList);
98 return li;
99 }
101 /**
102 * Add serializable fields.
103 *
104 * @param heading the heading for the section
105 * @param serializableFieldsTree the tree to be added to the serializable fileds
106 * content tree
107 * @return a content tree for the serializable fields content
108 */
109 public Content getSerializableFields(String heading, Content serializableFieldsTree) {
110 HtmlTree li = new HtmlTree(HtmlTag.LI);
111 li.addStyle(HtmlStyle.blockList);
112 if (serializableFieldsTree.isValid()) {
113 if (!printedOverallAnchor) {
114 li.addContent(writer.getMarkerAnchor("serializedForm"));
115 printedOverallAnchor = true;
116 }
117 Content headingContent = new StringContent(heading);
118 Content serialHeading = HtmlTree.HEADING(HtmlConstants.SERIALIZED_MEMBER_HEADING,
119 headingContent);
120 li.addContent(serialHeading);
121 li.addContent(serializableFieldsTree);
122 }
123 return li;
124 }
126 /**
127 * Add the member header.
128 *
129 * @param fieldType the class document to be listed
130 * @param fieldTypeStr the string for the field type to be documented
131 * @param fieldDimensions the dimensions of the field string to be added
132 * @param fieldName name of the field to be added
133 * @param contentTree the content tree to which the member header will be added
134 */
135 public void addMemberHeader(ClassDoc fieldType, String fieldTypeStr,
136 String fieldDimensions, String fieldName, Content contentTree) {
137 Content nameContent = new RawHtml(fieldName);
138 Content heading = HtmlTree.HEADING(HtmlConstants.MEMBER_HEADING, nameContent);
139 contentTree.addContent(heading);
140 Content pre = new HtmlTree(HtmlTag.PRE);
141 if (fieldType == null) {
142 pre.addContent(fieldTypeStr);
143 } else {
144 Content fieldContent = new RawHtml(writer.getLink(new LinkInfoImpl(
145 LinkInfoImpl.CONTEXT_SERIAL_MEMBER, fieldType)));
146 pre.addContent(fieldContent);
147 }
148 pre.addContent(fieldDimensions + " ");
149 pre.addContent(fieldName);
150 contentTree.addContent(pre);
151 }
153 /**
154 * Add the deprecated information 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 addMemberDeprecatedInfo(FieldDoc field, Content contentTree) {
160 addDeprecatedInfo(field, contentTree);
161 }
163 /**
164 * Add the description text for this member.
165 *
166 * @param field the field to document.
167 * @param contentTree the tree to which the deprecated info will be added
168 */
169 public void addMemberDescription(FieldDoc field, Content contentTree) {
170 if (field.inlineTags().length > 0) {
171 writer.addInlineComment(field, contentTree);
172 }
173 Tag[] tags = field.tags("serial");
174 if (tags.length > 0) {
175 writer.addInlineComment(field, tags[0], contentTree);
176 }
177 }
179 /**
180 * Add the description text for this member represented by the tag.
181 *
182 * @param serialFieldTag the field to document (represented by tag)
183 * @param contentTree the tree to which the deprecated info will be added
184 */
185 public void addMemberDescription(SerialFieldTag serialFieldTag, Content contentTree) {
186 String serialFieldTagDesc = serialFieldTag.description().trim();
187 if (!serialFieldTagDesc.isEmpty()) {
188 Content serialFieldContent = new RawHtml(serialFieldTagDesc);
189 Content div = HtmlTree.DIV(HtmlStyle.block, serialFieldContent);
190 contentTree.addContent(div);
191 }
192 }
194 /**
195 * Add the tag information for this member.
196 *
197 * @param field the field to document.
198 * @param contentTree the tree to which the member tags info will be added
199 */
200 public void addMemberTags(FieldDoc field, Content contentTree) {
201 TagletOutputImpl output = new TagletOutputImpl("");
202 TagletWriter.genTagOuput(configuration().tagletManager, field,
203 configuration().tagletManager.getCustomTags(field),
204 writer.getTagletWriterInstance(false), output);
205 String outputString = output.toString().trim();
206 Content dlTags = new HtmlTree(HtmlTag.DL);
207 if (!outputString.isEmpty()) {
208 Content tagContent = new RawHtml(outputString);
209 dlTags.addContent(tagContent);
210 }
211 contentTree.addContent(dlTags);
212 }
214 /**
215 * Check to see if overview details should be printed. If
216 * nocomment option set or if there is no text to be printed
217 * for deprecation info, comment or tags, do not print overview details.
218 *
219 * @param field the field to check overview details for.
220 * @return true if overview details need to be printed
221 */
222 public boolean shouldPrintOverview(FieldDoc field) {
223 if (!configuration().nocomment) {
224 if(!field.commentText().isEmpty() ||
225 writer.hasSerializationOverviewTags(field))
226 return true;
227 }
228 if (field.tags("deprecated").length > 0)
229 return true;
230 return false;
231 }
232 }