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