Sat, 13 Apr 2013 18:48:29 -0700
8009686: Generated javadoc documentation should be able to display type annotation on an array
Reviewed-by: jjg
1 /*
2 * Copyright (c) 2003, 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 com.sun.javadoc.*;
29 import com.sun.tools.doclets.internal.toolkit.*;
30 import com.sun.tools.doclets.internal.toolkit.builders.SerializedFormBuilder;
31 import com.sun.tools.doclets.internal.toolkit.taglets.*;
32 import com.sun.tools.doclets.internal.toolkit.util.*;
34 /**
35 * The taglet writer that writes HTML.
36 *
37 * <p><b>This is NOT part of any supported API.
38 * If you write code that depends on this, you do so at your own risk.
39 * This code and its internal interfaces are subject to change or
40 * deletion without notice.</b>
41 *
42 * @since 1.5
43 * @author Jamie Ho
44 * @author Bhavesh Patel (Modified)
45 */
47 public class TagletWriterImpl extends TagletWriter {
49 private final HtmlDocletWriter htmlWriter;
50 private final ConfigurationImpl configuration;
52 public TagletWriterImpl(HtmlDocletWriter htmlWriter, boolean isFirstSentence) {
53 super(isFirstSentence);
54 this.htmlWriter = htmlWriter;
55 configuration = htmlWriter.configuration;
56 }
58 /**
59 * {@inheritDoc}
60 */
61 public TagletOutput getOutputInstance() {
62 return new TagletOutputImpl("");
63 }
65 /**
66 * {@inheritDoc}
67 */
68 public TagletOutput getDocRootOutput() {
69 if (configuration.docrootparent.length() > 0)
70 return new TagletOutputImpl(configuration.docrootparent);
71 else if (htmlWriter.pathToRoot.isEmpty())
72 return new TagletOutputImpl(".");
73 else
74 return new TagletOutputImpl(htmlWriter.pathToRoot.getPath());
75 }
77 /**
78 * {@inheritDoc}
79 */
80 public TagletOutput deprecatedTagOutput(Doc doc) {
81 StringBuilder output = new StringBuilder();
82 Tag[] deprs = doc.tags("deprecated");
83 if (doc instanceof ClassDoc) {
84 if (Util.isDeprecated((ProgramElementDoc) doc)) {
85 output.append("<span class=\"strong\">" +
86 configuration.
87 getText("doclet.Deprecated") + "</span> ");
88 if (deprs.length > 0) {
89 Tag[] commentTags = deprs[0].inlineTags();
90 if (commentTags.length > 0) {
92 output.append(commentTagsToOutput(null, doc,
93 deprs[0].inlineTags(), false).toString()
94 );
95 }
96 }
97 }
98 } else {
99 MemberDoc member = (MemberDoc) doc;
100 if (Util.isDeprecated((ProgramElementDoc) doc)) {
101 output.append("<span class=\"strong\">" +
102 configuration.
103 getText("doclet.Deprecated") + "</span> ");
104 if (deprs.length > 0) {
105 output.append("<i>");
106 output.append(commentTagsToOutput(null, doc,
107 deprs[0].inlineTags(), false).toString());
108 output.append("</i>");
109 }
110 } else {
111 if (Util.isDeprecated(member.containingClass())) {
112 output.append("<span class=\"strong\">" +
113 configuration.
114 getText("doclet.Deprecated") + "</span> ");
115 }
116 }
117 }
118 return new TagletOutputImpl(output.toString());
119 }
121 /**
122 * {@inheritDoc}
123 */
124 public MessageRetriever getMsgRetriever() {
125 return configuration.message;
126 }
128 /**
129 * {@inheritDoc}
130 */
131 public TagletOutput getParamHeader(String header) {
132 StringBuilder result = new StringBuilder();
133 result.append("<dt>");
134 result.append("<span class=\"strong\">").append(header).append("</span></dt>");
135 return new TagletOutputImpl(result.toString());
136 }
138 /**
139 * {@inheritDoc}
140 */
141 public TagletOutput paramTagOutput(ParamTag paramTag, String paramName) {
142 TagletOutput result = new TagletOutputImpl("<dd><code>" + paramName + "</code>"
143 + " - " + htmlWriter.commentTagsToString(paramTag, null, paramTag.inlineTags(), false) + "</dd>");
144 return result;
145 }
147 /**
148 * {@inheritDoc}
149 */
150 public TagletOutput returnTagOutput(Tag returnTag) {
151 TagletOutput result = new TagletOutputImpl(DocletConstants.NL + "<dt>" +
152 "<span class=\"strong\">" + configuration.getText("doclet.Returns") +
153 "</span>" + "</dt>" + "<dd>" +
154 htmlWriter.commentTagsToString(returnTag, null, returnTag.inlineTags(),
155 false) + "</dd>");
156 return result;
157 }
159 /**
160 * {@inheritDoc}
161 */
162 public TagletOutput seeTagOutput(Doc holder, SeeTag[] seeTags) {
163 String result = "";
164 if (seeTags.length > 0) {
165 result = addSeeHeader(result);
166 for (int i = 0; i < seeTags.length; ++i) {
167 if (i > 0) {
168 result += ", " + DocletConstants.NL;
169 }
170 result += htmlWriter.seeTagToString(seeTags[i]);
171 }
172 }
173 if (holder.isField() && ((FieldDoc)holder).constantValue() != null &&
174 htmlWriter instanceof ClassWriterImpl) {
175 //Automatically add link to constant values page for constant fields.
176 result = addSeeHeader(result);
177 DocPath constantsPath =
178 htmlWriter.pathToRoot.resolve(DocPaths.CONSTANT_VALUES);
179 String whichConstant =
180 ((ClassWriterImpl) htmlWriter).getClassDoc().qualifiedName() + "." + ((FieldDoc) holder).name();
181 DocLink link = constantsPath.fragment(whichConstant);
182 result += htmlWriter.getHyperLinkString(link,
183 configuration.getText("doclet.Constants_Summary"),
184 false);
185 }
186 if (holder.isClass() && ((ClassDoc)holder).isSerializable()) {
187 //Automatically add link to serialized form page for serializable classes.
188 if ((SerializedFormBuilder.serialInclude(holder) &&
189 SerializedFormBuilder.serialInclude(((ClassDoc)holder).containingPackage()))) {
190 result = addSeeHeader(result);
191 DocPath serialPath = htmlWriter.pathToRoot.resolve(DocPaths.SERIALIZED_FORM);
192 DocLink link = serialPath.fragment(((ClassDoc)holder).qualifiedName());
193 result += htmlWriter.getHyperLinkString(link,
194 configuration.getText("doclet.Serialized_Form"), false);
195 }
196 }
197 return result.equals("") ? null : new TagletOutputImpl(result + "</dd>");
198 }
200 private String addSeeHeader(String result) {
201 if (result != null && result.length() > 0) {
202 return result + ", " + DocletConstants.NL;
203 } else {
204 return "<dt><span class=\"strong\">" +
205 configuration.getText("doclet.See_Also") + "</span></dt><dd>";
206 }
207 }
209 /**
210 * {@inheritDoc}
211 */
212 public TagletOutput simpleTagOutput(Tag[] simpleTags, String header) {
213 String result = "<dt><span class=\"strong\">" + header + "</span></dt>" + DocletConstants.NL +
214 " <dd>";
215 for (int i = 0; i < simpleTags.length; i++) {
216 if (i > 0) {
217 result += ", ";
218 }
219 result += htmlWriter.commentTagsToString(simpleTags[i], null, simpleTags[i].inlineTags(), false);
220 }
221 result += "</dd>" + DocletConstants.NL;
222 return new TagletOutputImpl(result);
223 }
225 /**
226 * {@inheritDoc}
227 */
228 public TagletOutput simpleTagOutput(Tag simpleTag, String header) {
229 return new TagletOutputImpl("<dt><span class=\"strong\">" + header + "</span></dt>" + " <dd>"
230 + htmlWriter.commentTagsToString(simpleTag, null, simpleTag.inlineTags(), false)
231 + "</dd>" + DocletConstants.NL);
232 }
234 /**
235 * {@inheritDoc}
236 */
237 public TagletOutput getThrowsHeader() {
238 return new TagletOutputImpl(DocletConstants.NL + "<dt>" + "<span class=\"strong\">" +
239 configuration.getText("doclet.Throws") + "</span></dt>");
240 }
242 /**
243 * {@inheritDoc}
244 */
245 public TagletOutput throwsTagOutput(ThrowsTag throwsTag) {
246 String result = DocletConstants.NL + "<dd>";
247 result += throwsTag.exceptionType() == null ?
248 htmlWriter.codeText(throwsTag.exceptionName()) :
249 htmlWriter.codeText(
250 htmlWriter.getLink(new LinkInfoImpl(configuration, LinkInfoImpl.CONTEXT_MEMBER,
251 throwsTag.exceptionType())));
252 TagletOutput text = new TagletOutputImpl(
253 htmlWriter.commentTagsToString(throwsTag, null,
254 throwsTag.inlineTags(), false));
255 if (text != null && text.toString().length() > 0) {
256 result += " - " + text;
257 }
258 result += "</dd>";
259 return new TagletOutputImpl(result);
260 }
262 /**
263 * {@inheritDoc}
264 */
265 public TagletOutput throwsTagOutput(Type throwsType) {
266 return new TagletOutputImpl(DocletConstants.NL + "<dd>" +
267 htmlWriter.codeText(htmlWriter.getLink(
268 new LinkInfoImpl(configuration, LinkInfoImpl.CONTEXT_MEMBER, throwsType))) + "</dd>");
269 }
271 /**
272 * {@inheritDoc}
273 */
274 public TagletOutput valueTagOutput(FieldDoc field, String constantVal,
275 boolean includeLink) {
276 return new TagletOutputImpl(includeLink ?
277 htmlWriter.getDocLink(LinkInfoImpl.CONTEXT_VALUE_TAG, field,
278 constantVal, false) : constantVal);
279 }
281 /**
282 * {@inheritDoc}
283 */
284 public TagletOutput commentTagsToOutput(Tag holderTag, Tag[] tags) {
285 return commentTagsToOutput(holderTag, null, tags, false);
286 }
288 /**
289 * {@inheritDoc}
290 */
291 public TagletOutput commentTagsToOutput(Doc holderDoc, Tag[] tags) {
292 return commentTagsToOutput(null, holderDoc, tags, false);
293 }
295 /**
296 * {@inheritDoc}
297 */
298 public TagletOutput commentTagsToOutput(Tag holderTag,
299 Doc holderDoc, Tag[] tags, boolean isFirstSentence) {
300 return new TagletOutputImpl(htmlWriter.commentTagsToString(
301 holderTag, holderDoc, tags, isFirstSentence));
302 }
304 /**
305 * {@inheritDoc}
306 */
307 public Configuration configuration() {
308 return configuration;
309 }
311 /**
312 * Return an instance of a TagletWriter that knows how to write HTML.
313 *
314 * @return an instance of a TagletWriter that knows how to write HTML.
315 */
316 public TagletOutput getTagletOutputInstance() {
317 return new TagletOutputImpl("");
318 }
319 }