Tue, 14 May 2013 10:14:54 -0700
8012175: Convert TagletOutputImpl to use ContentBuilder instead of StringBuilder
Reviewed-by: darcy
1 /*
2 * Copyright (c) 1997, 2013, 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.io.*;
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.util.*;
35 /**
36 * Writes method documentation in HTML format.
37 *
38 * <p><b>This is NOT part of any supported API.
39 * If you write code that depends on this, you do so at your own risk.
40 * This code and its internal interfaces are subject to change or
41 * deletion without notice.</b>
42 *
43 * @author Robert Field
44 * @author Atul M Dambalkar
45 * @author Jamie Ho (rewrite)
46 * @author Bhavesh Patel (Modified)
47 */
48 public class MethodWriterImpl extends AbstractExecutableMemberWriter
49 implements MethodWriter, MemberSummaryWriter {
51 /**
52 * Construct a new MethodWriterImpl.
53 *
54 * @param writer the writer for the class that the methods belong to.
55 * @param classDoc the class being documented.
56 */
57 public MethodWriterImpl(SubWriterHolderWriter writer, ClassDoc classDoc) {
58 super(writer, classDoc);
59 }
61 /**
62 * Construct a new MethodWriterImpl.
63 *
64 * @param writer The writer for the class that the methods belong to.
65 */
66 public MethodWriterImpl(SubWriterHolderWriter writer) {
67 super(writer);
68 }
70 /**
71 * {@inheritDoc}
72 */
73 public Content getMemberSummaryHeader(ClassDoc classDoc,
74 Content memberSummaryTree) {
75 memberSummaryTree.addContent(HtmlConstants.START_OF_METHOD_SUMMARY);
76 Content memberTree = writer.getMemberTreeHeader();
77 writer.addSummaryHeader(this, classDoc, memberTree);
78 return memberTree;
79 }
81 /**
82 * {@inheritDoc}
83 */
84 public Content getMethodDetailsTreeHeader(ClassDoc classDoc,
85 Content memberDetailsTree) {
86 memberDetailsTree.addContent(HtmlConstants.START_OF_METHOD_DETAILS);
87 Content methodDetailsTree = writer.getMemberTreeHeader();
88 methodDetailsTree.addContent(writer.getMarkerAnchor("method_detail"));
89 Content heading = HtmlTree.HEADING(HtmlConstants.DETAILS_HEADING,
90 writer.methodDetailsLabel);
91 methodDetailsTree.addContent(heading);
92 return methodDetailsTree;
93 }
95 /**
96 * {@inheritDoc}
97 */
98 public Content getMethodDocTreeHeader(MethodDoc method,
99 Content methodDetailsTree) {
100 String erasureAnchor;
101 if ((erasureAnchor = getErasureAnchor(method)) != null) {
102 methodDetailsTree.addContent(writer.getMarkerAnchor((erasureAnchor)));
103 }
104 methodDetailsTree.addContent(
105 writer.getMarkerAnchor(writer.getAnchor(method)));
106 Content methodDocTree = writer.getMemberTreeHeader();
107 Content heading = new HtmlTree(HtmlConstants.MEMBER_HEADING);
108 heading.addContent(method.name());
109 methodDocTree.addContent(heading);
110 return methodDocTree;
111 }
113 /**
114 * Get the signature for the given method.
115 *
116 * @param method the method being documented.
117 * @return a content object for the signature
118 */
119 public Content getSignature(MethodDoc method) {
120 Content pre = new HtmlTree(HtmlTag.PRE);
121 writer.addAnnotationInfo(method, pre);
122 addModifiers(method, pre);
123 addTypeParameters(method, pre);
124 addReturnType(method, pre);
125 if (configuration.linksource) {
126 Content methodName = new StringContent(method.name());
127 writer.addSrcLink(method, methodName, pre);
128 } else {
129 addName(method.name(), pre);
130 }
131 int indent = pre.charCount();
132 addParameters(method, pre, indent);
133 addExceptions(method, pre, indent);
134 return pre;
135 }
137 /**
138 * {@inheritDoc}
139 */
140 public void addDeprecated(MethodDoc method, Content methodDocTree) {
141 addDeprecatedInfo(method, methodDocTree);
142 }
144 /**
145 * {@inheritDoc}
146 */
147 public void addComments(Type holder, MethodDoc method, Content methodDocTree) {
148 ClassDoc holderClassDoc = holder.asClassDoc();
149 if (method.inlineTags().length > 0) {
150 if (holder.asClassDoc().equals(classdoc) ||
151 (! (holderClassDoc.isPublic() ||
152 Util.isLinkable(holderClassDoc, configuration)))) {
153 writer.addInlineComment(method, methodDocTree);
154 } else {
155 Content link =
156 writer.getDocLink(LinkInfoImpl.Kind.METHOD_DOC_COPY,
157 holder.asClassDoc(), method,
158 holder.asClassDoc().isIncluded() ?
159 holder.typeName() : holder.qualifiedTypeName(),
160 false);
161 Content codelLink = HtmlTree.CODE(link);
162 Content strong = HtmlTree.STRONG(holder.asClassDoc().isClass()?
163 writer.descfrmClassLabel : writer.descfrmInterfaceLabel);
164 strong.addContent(writer.getSpace());
165 strong.addContent(codelLink);
166 methodDocTree.addContent(HtmlTree.DIV(HtmlStyle.block, strong));
167 writer.addInlineComment(method, methodDocTree);
168 }
169 }
170 }
172 /**
173 * {@inheritDoc}
174 */
175 public void addTags(MethodDoc method, Content methodDocTree) {
176 writer.addTagsInfo(method, methodDocTree);
177 }
179 /**
180 * {@inheritDoc}
181 */
182 public Content getMethodDetails(Content methodDetailsTree) {
183 return getMemberTree(methodDetailsTree);
184 }
186 /**
187 * {@inheritDoc}
188 */
189 public Content getMethodDoc(Content methodDocTree,
190 boolean isLastContent) {
191 return getMemberTree(methodDocTree, isLastContent);
192 }
194 /**
195 * Close the writer.
196 */
197 public void close() throws IOException {
198 writer.close();
199 }
201 public int getMemberKind() {
202 return VisibleMemberMap.METHODS;
203 }
205 /**
206 * {@inheritDoc}
207 */
208 public void addSummaryLabel(Content memberTree) {
209 Content label = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING,
210 writer.getResource("doclet.Method_Summary"));
211 memberTree.addContent(label);
212 }
214 /**
215 * {@inheritDoc}
216 */
217 public String getTableSummary() {
218 return configuration.getText("doclet.Member_Table_Summary",
219 configuration.getText("doclet.Method_Summary"),
220 configuration.getText("doclet.methods"));
221 }
223 /**
224 * {@inheritDoc}
225 */
226 public String getCaption() {
227 return configuration.getText("doclet.Methods");
228 }
230 /**
231 * {@inheritDoc}
232 */
233 public String[] getSummaryTableHeader(ProgramElementDoc member) {
234 String[] header = new String[] {
235 writer.getModifierTypeHeader(),
236 configuration.getText("doclet.0_and_1",
237 configuration.getText("doclet.Method"),
238 configuration.getText("doclet.Description"))
239 };
240 return header;
241 }
243 /**
244 * {@inheritDoc}
245 */
246 public void addSummaryAnchor(ClassDoc cd, Content memberTree) {
247 memberTree.addContent(writer.getMarkerAnchor("method_summary"));
248 }
250 /**
251 * {@inheritDoc}
252 */
253 public void addInheritedSummaryAnchor(ClassDoc cd, Content inheritedTree) {
254 inheritedTree.addContent(writer.getMarkerAnchor(
255 "methods_inherited_from_class_" +
256 configuration.getClassName(cd)));
257 }
259 /**
260 * {@inheritDoc}
261 */
262 public void addInheritedSummaryLabel(ClassDoc cd, Content inheritedTree) {
263 Content classLink = writer.getPreQualifiedClassLink(
264 LinkInfoImpl.Kind.MEMBER, cd, false);
265 Content label = new StringContent(cd.isClass() ?
266 configuration.getText("doclet.Methods_Inherited_From_Class") :
267 configuration.getText("doclet.Methods_Inherited_From_Interface"));
268 Content labelHeading = HtmlTree.HEADING(HtmlConstants.INHERITED_SUMMARY_HEADING,
269 label);
270 labelHeading.addContent(writer.getSpace());
271 labelHeading.addContent(classLink);
272 inheritedTree.addContent(labelHeading);
273 }
275 /**
276 * {@inheritDoc}
277 */
278 protected void addSummaryType(ProgramElementDoc member, Content tdSummaryType) {
279 MethodDoc meth = (MethodDoc)member;
280 addModifierAndType(meth, meth.returnType(), tdSummaryType);
281 }
283 /**
284 * {@inheritDoc}
285 */
286 protected static void addOverridden(HtmlDocletWriter writer,
287 Type overriddenType, MethodDoc method, Content dl) {
288 if (writer.configuration.nocomment) {
289 return;
290 }
291 ClassDoc holderClassDoc = overriddenType.asClassDoc();
292 if (! (holderClassDoc.isPublic() ||
293 Util.isLinkable(holderClassDoc, writer.configuration))) {
294 //This is an implementation detail that should not be documented.
295 return;
296 }
297 if (overriddenType.asClassDoc().isIncluded() && ! method.isIncluded()) {
298 //The class is included but the method is not. That means that it
299 //is not visible so don't document this.
300 return;
301 }
302 Content label = writer.overridesLabel;
303 LinkInfoImpl.Kind context = LinkInfoImpl.Kind.METHOD_OVERRIDES;
305 if (method != null) {
306 if (overriddenType.asClassDoc().isAbstract() && method.isAbstract()){
307 //Abstract method is implemented from abstract class,
308 //not overridden
309 label = writer.specifiedByLabel;
310 context = LinkInfoImpl.Kind.METHOD_SPECIFIED_BY;
311 }
312 Content dt = HtmlTree.DT(HtmlTree.STRONG(label));
313 dl.addContent(dt);
314 Content overriddenTypeLink =
315 writer.getLink(new LinkInfoImpl(writer.configuration, context, overriddenType));
316 Content codeOverridenTypeLink = HtmlTree.CODE(overriddenTypeLink);
317 String name = method.name();
318 Content methlink = writer.getLink(
319 new LinkInfoImpl(writer.configuration, LinkInfoImpl.Kind.MEMBER,
320 overriddenType.asClassDoc())
321 .where(writer.getAnchor(method)).label(name));
322 Content codeMethLink = HtmlTree.CODE(methlink);
323 Content dd = HtmlTree.DD(codeMethLink);
324 dd.addContent(writer.getSpace());
325 dd.addContent(writer.getResource("doclet.in_class"));
326 dd.addContent(writer.getSpace());
327 dd.addContent(codeOverridenTypeLink);
328 dl.addContent(dd);
329 }
330 }
332 /**
333 * Parse the <Code> tag and return the text.
334 */
335 protected String parseCodeTag(String tag){
336 if(tag == null){
337 return "";
338 }
340 String lc = tag.toLowerCase();
341 int begin = lc.indexOf("<code>");
342 int end = lc.indexOf("</code>");
343 if(begin == -1 || end == -1 || end <= begin){
344 return tag;
345 } else {
346 return tag.substring(begin + 6, end);
347 }
348 }
350 /**
351 * {@inheritDoc}
352 */
353 protected static void addImplementsInfo(HtmlDocletWriter writer,
354 MethodDoc method, Content dl) {
355 if(writer.configuration.nocomment){
356 return;
357 }
358 ImplementedMethods implementedMethodsFinder =
359 new ImplementedMethods(method, writer.configuration);
360 MethodDoc[] implementedMethods = implementedMethodsFinder.build();
361 for (int i = 0; i < implementedMethods.length; i++) {
362 MethodDoc implementedMeth = implementedMethods[i];
363 Type intfac = implementedMethodsFinder.getMethodHolder(implementedMeth);
364 Content intfaclink = writer.getLink(new LinkInfoImpl(
365 writer.configuration, LinkInfoImpl.Kind.METHOD_SPECIFIED_BY, intfac));
366 Content codeIntfacLink = HtmlTree.CODE(intfaclink);
367 Content dt = HtmlTree.DT(HtmlTree.STRONG(writer.specifiedByLabel));
368 dl.addContent(dt);
369 Content methlink = writer.getDocLink(
370 LinkInfoImpl.Kind.MEMBER, implementedMeth,
371 implementedMeth.name(), false);
372 Content codeMethLink = HtmlTree.CODE(methlink);
373 Content dd = HtmlTree.DD(codeMethLink);
374 dd.addContent(writer.getSpace());
375 dd.addContent(writer.getResource("doclet.in_interface"));
376 dd.addContent(writer.getSpace());
377 dd.addContent(codeIntfacLink);
378 dl.addContent(dd);
379 }
380 }
382 /**
383 * Add the return type.
384 *
385 * @param method the method being documented.
386 * @param htmltree the content tree to which the return type will be added
387 */
388 protected void addReturnType(MethodDoc method, Content htmltree) {
389 Type type = method.returnType();
390 if (type != null) {
391 Content linkContent = writer.getLink(
392 new LinkInfoImpl(configuration, LinkInfoImpl.Kind.RETURN_TYPE, type));
393 htmltree.addContent(linkContent);
394 htmltree.addContent(writer.getSpace());
395 }
396 }
398 /**
399 * {@inheritDoc}
400 */
401 protected Content getNavSummaryLink(ClassDoc cd, boolean link) {
402 if (link) {
403 return writer.getHyperLink((cd == null)?
404 "method_summary":
405 "methods_inherited_from_class_" +
406 configuration.getClassName(cd),
407 writer.getResource("doclet.navMethod"));
408 } else {
409 return writer.getResource("doclet.navMethod");
410 }
411 }
413 /**
414 * {@inheritDoc}
415 */
416 protected void addNavDetailLink(boolean link, Content liNav) {
417 if (link) {
418 liNav.addContent(writer.getHyperLink("method_detail",
419 writer.getResource("doclet.navMethod")));
420 } else {
421 liNav.addContent(writer.getResource("doclet.navMethod"));
422 }
423 }
424 }