Fri, 27 Feb 2009 18:57:17 -0800
6786690: Javadoc HTML WCAG 2.0 accessibility issues in standard doclet - DL tag and nesting issue
Reviewed-by: jjg
1 /*
2 * Copyright 2003-2005 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any 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 * @since 1.5
38 * @author Jamie Ho
39 * @author Bhavesh Patel (Modified)
40 */
42 public class TagletWriterImpl extends TagletWriter {
44 private HtmlDocletWriter htmlWriter;
46 public TagletWriterImpl(HtmlDocletWriter htmlWriter, boolean isFirstSentence) {
47 this.htmlWriter = htmlWriter;
48 this.isFirstSentence = isFirstSentence;
49 }
51 /**
52 * {@inheritDoc}
53 */
54 public TagletOutput getOutputInstance() {
55 return new TagletOutputImpl("");
56 }
58 /**
59 * {@inheritDoc}
60 */
61 public TagletOutput getDocRootOutput() {
62 return new TagletOutputImpl(htmlWriter.relativepathNoSlash);
63 }
65 /**
66 * {@inheritDoc}
67 */
68 public TagletOutput deprecatedTagOutput(Doc doc) {
69 StringBuffer output = new StringBuffer();
70 Tag[] deprs = doc.tags("deprecated");
71 if (doc instanceof ClassDoc) {
72 if (Util.isDeprecated((ProgramElementDoc) doc)) {
73 output.append("<STRONG>" +
74 ConfigurationImpl.getInstance().
75 getText("doclet.Deprecated") + "</STRONG> ");
76 if (deprs.length > 0) {
77 Tag[] commentTags = deprs[0].inlineTags();
78 if (commentTags.length > 0) {
80 output.append(commentTagsToOutput(null, doc,
81 deprs[0].inlineTags(), false).toString()
82 );
83 }
84 }
85 output.append("<p>");
86 }
87 } else {
88 MemberDoc member = (MemberDoc) doc;
89 if (Util.isDeprecated((ProgramElementDoc) doc)) {
90 output.append("<DD><STRONG>" +
91 ConfigurationImpl.getInstance().
92 getText("doclet.Deprecated") + "</STRONG> ");
93 if (deprs.length > 0) {
94 output.append("<I>");
95 output.append(commentTagsToOutput(null, doc,
96 deprs[0].inlineTags(), false).toString());
97 output.append("</I>");
98 }
99 if (member instanceof ExecutableMemberDoc) {
100 output.append(DocletConstants.NL + "<P>" +
101 DocletConstants.NL);
102 }
103 output.append("</DD>");
104 } else {
105 if (Util.isDeprecated(member.containingClass())) {
106 output.append("<DD><STRONG>" +
107 ConfigurationImpl.getInstance().
108 getText("doclet.Deprecated") + "</STRONG> </DD>");
109 }
110 }
111 }
112 return new TagletOutputImpl(output.toString());
113 }
115 /**
116 * {@inheritDoc}
117 */
118 public MessageRetriever getMsgRetriever() {
119 return htmlWriter.configuration.message;
120 }
122 /**
123 * {@inheritDoc}
124 */
125 public TagletOutput getParamHeader(String header) {
126 StringBuffer result = new StringBuffer();
127 result.append("<DT>");
128 result.append("<STRONG>" + header + "</STRONG></DT>");
129 return new TagletOutputImpl(result.toString());
130 }
132 /**
133 * {@inheritDoc}
134 */
135 public TagletOutput paramTagOutput(ParamTag paramTag, String paramName) {
136 TagletOutput result = new TagletOutputImpl("<DD><CODE>" + paramName + "</CODE>"
137 + " - " + htmlWriter.commentTagsToString(paramTag, null, paramTag.inlineTags(), false) + "</DD>");
138 return result;
139 }
141 /**
142 * {@inheritDoc}
143 */
144 public TagletOutput returnTagOutput(Tag returnTag) {
145 TagletOutput result = new TagletOutputImpl(DocletConstants.NL + "<DT>" +
146 "<STRONG>" + htmlWriter.configuration.getText("doclet.Returns") +
147 "</STRONG>" + "</DT>" + "<DD>" +
148 htmlWriter.commentTagsToString(returnTag, null, returnTag.inlineTags(),
149 false) + "</DD>");
150 return result;
151 }
153 /**
154 * {@inheritDoc}
155 */
156 public TagletOutput seeTagOutput(Doc holder, SeeTag[] seeTags) {
157 String result = "";
158 if (seeTags.length > 0) {
159 result = addSeeHeader(result);
160 for (int i = 0; i < seeTags.length; ++i) {
161 if (i > 0) {
162 result += ", " + DocletConstants.NL;
163 }
164 result += htmlWriter.seeTagToString(seeTags[i]);
165 }
166 }
167 if (holder.isField() && ((FieldDoc)holder).constantValue() != null &&
168 htmlWriter instanceof ClassWriterImpl) {
169 //Automatically add link to constant values page for constant fields.
170 result = addSeeHeader(result);
171 result += htmlWriter.getHyperLink(htmlWriter.relativePath +
172 ConfigurationImpl.CONSTANTS_FILE_NAME
173 + "#" + ((ClassWriterImpl) htmlWriter).getClassDoc().qualifiedName()
174 + "." + ((FieldDoc) holder).name(),
175 htmlWriter.configuration.getText("doclet.Constants_Summary"));
176 }
177 if (holder.isClass() && ((ClassDoc)holder).isSerializable()) {
178 //Automatically add link to serialized form page for serializable classes.
179 if ((SerializedFormBuilder.serialInclude(holder) &&
180 SerializedFormBuilder.serialInclude(((ClassDoc)holder).containingPackage()))) {
181 result = addSeeHeader(result);
182 result += htmlWriter.getHyperLink(htmlWriter.relativePath + "serialized-form.html",
183 ((ClassDoc)holder).qualifiedName(), htmlWriter.configuration.getText("doclet.Serialized_Form"), false);
184 }
185 }
186 return result.equals("") ? null : new TagletOutputImpl(result + "</DD>");
187 }
189 private String addSeeHeader(String result) {
190 if (result != null && result.length() > 0) {
191 return result + ", " + DocletConstants.NL;
192 } else {
193 return "<DT><STRONG>" + htmlWriter.configuration().getText("doclet.See_Also") + "</STRONG></DT><DD>";
194 }
195 }
197 /**
198 * {@inheritDoc}
199 */
200 public TagletOutput simpleTagOutput(Tag[] simpleTags, String header) {
201 String result = "<DT><STRONG>" + header + "</STRONG></DT>" + DocletConstants.NL +
202 " <DD>";
203 for (int i = 0; i < simpleTags.length; i++) {
204 if (i > 0) {
205 result += ", ";
206 }
207 result += htmlWriter.commentTagsToString(simpleTags[i], null, simpleTags[i].inlineTags(), false);
208 }
209 result += "</DD>" + DocletConstants.NL;
210 return new TagletOutputImpl(result);
211 }
213 /**
214 * {@inheritDoc}
215 */
216 public TagletOutput simpleTagOutput(Tag simpleTag, String header) {
217 return new TagletOutputImpl("<DT><STRONG>" + header + "</STRONG></DT>" + " <DD>"
218 + htmlWriter.commentTagsToString(simpleTag, null, simpleTag.inlineTags(), false)
219 + "</DD>" + DocletConstants.NL);
220 }
222 /**
223 * {@inheritDoc}
224 */
225 public TagletOutput getThrowsHeader() {
226 return new TagletOutputImpl(DocletConstants.NL + "<DT>" + "<STRONG>" +
227 htmlWriter.configuration().getText("doclet.Throws") + "</STRONG></DT>");
228 }
230 /**
231 * {@inheritDoc}
232 */
233 public TagletOutput throwsTagOutput(ThrowsTag throwsTag) {
234 String result = DocletConstants.NL + "<DD>";
235 result += throwsTag.exceptionType() == null ?
236 htmlWriter.codeText(throwsTag.exceptionName()) :
237 htmlWriter.codeText(
238 htmlWriter.getLink(new LinkInfoImpl(LinkInfoImpl.CONTEXT_MEMBER,
239 throwsTag.exceptionType())));
240 TagletOutput text = new TagletOutputImpl(
241 htmlWriter.commentTagsToString(throwsTag, null,
242 throwsTag.inlineTags(), false));
243 if (text != null && text.toString().length() > 0) {
244 result += " - " + text;
245 }
246 result += "</DD>";
247 return new TagletOutputImpl(result);
248 }
250 /**
251 * {@inheritDoc}
252 */
253 public TagletOutput throwsTagOutput(Type throwsType) {
254 return new TagletOutputImpl(DocletConstants.NL + "<DD>" +
255 htmlWriter.codeText(htmlWriter.getLink(
256 new LinkInfoImpl(LinkInfoImpl.CONTEXT_MEMBER, throwsType))) + "</DD>");
257 }
259 /**
260 * {@inheritDoc}
261 */
262 public TagletOutput valueTagOutput(FieldDoc field, String constantVal,
263 boolean includeLink) {
264 return new TagletOutputImpl(includeLink ?
265 htmlWriter.getDocLink(LinkInfoImpl.CONTEXT_VALUE_TAG, field,
266 constantVal, false) : constantVal);
267 }
269 /**
270 * {@inheritDoc}
271 */
272 public TagletOutput commentTagsToOutput(Tag holderTag, Tag[] tags) {
273 return commentTagsToOutput(holderTag, null, tags, false);
274 }
276 /**
277 * {@inheritDoc}
278 */
279 public TagletOutput commentTagsToOutput(Doc holderDoc, Tag[] tags) {
280 return commentTagsToOutput(null, holderDoc, tags, false);
281 }
283 /**
284 * {@inheritDoc}
285 */
286 public TagletOutput commentTagsToOutput(Tag holderTag,
287 Doc holderDoc, Tag[] tags, boolean isFirstSentence) {
288 return new TagletOutputImpl(htmlWriter.commentTagsToString(
289 holderTag, holderDoc, tags, isFirstSentence));
290 }
292 /**
293 * {@inheritDoc}
294 */
295 public Configuration configuration() {
296 return htmlWriter.configuration();
297 }
299 /**
300 * Return an instance of a TagletWriter that knows how to write HTML.
301 *
302 * @return an instance of a TagletWriter that knows how to write HTML.
303 */
304 public TagletOutput getTagletOutputInstance() {
305 return new TagletOutputImpl("");
306 }
307 }