Sun, 11 Apr 2010 23:24:24 -0700
6875904: Java 7 message synchronization 1
Reviewed-by: ogino, faryad
1 /*
2 * Copyright 1997-2004 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 java.io.*;
30 import com.sun.javadoc.*;
31 import com.sun.tools.doclets.internal.toolkit.*;
32 import com.sun.tools.doclets.internal.toolkit.util.*;
33 import com.sun.tools.doclets.internal.toolkit.taglets.*;
35 /**
36 * Writes method documentation in HTML format.
37 *
38 * @author Robert Field
39 * @author Atul M Dambalkar
40 * @author Jamie Ho (rewrite)
41 * @author Bhavesh Patel (Modified)
42 */
43 public class MethodWriterImpl extends AbstractExecutableMemberWriter
44 implements MethodWriter, MemberSummaryWriter {
46 private boolean printedSummaryHeader = false;
48 /**
49 * Construct a new MethodWriterImpl.
50 *
51 * @param writer the writer for the class that the methods belong to.
52 * @param classDoc the class being documented.
53 */
54 public MethodWriterImpl(SubWriterHolderWriter writer, ClassDoc classDoc) {
55 super(writer, classDoc);
56 }
58 /**
59 * Construct a new MethodWriterImpl.
60 *
61 * @param writer The writer for the class that the methods belong to.
62 */
63 public MethodWriterImpl(SubWriterHolderWriter writer) {
64 super(writer);
65 }
67 /**
68 * Write the methods summary header for the given class.
69 *
70 * @param classDoc the class the summary belongs to.
71 */
72 public void writeMemberSummaryHeader(ClassDoc classDoc) {
73 printedSummaryHeader = true;
74 writer.println();
75 writer.println("<!-- ========== METHOD SUMMARY =========== -->");
76 writer.println();
77 writer.printSummaryHeader(this, classDoc);
78 }
80 /**
81 * Write the methods summary footer for the given class.
82 *
83 * @param classDoc the class the summary belongs to.
84 */
85 public void writeMemberSummaryFooter(ClassDoc classDoc) {
86 writer.printSummaryFooter(this, classDoc);
87 }
89 /**
90 * Write the inherited methods summary header for the given class.
91 *
92 * @param classDoc the class the summary belongs to.
93 */
94 public void writeInheritedMemberSummaryHeader(ClassDoc classDoc) {
95 if(! printedSummaryHeader){
96 //We don't want inherited summary to not be under heading.
97 writeMemberSummaryHeader(classDoc);
98 writeMemberSummaryFooter(classDoc);
99 printedSummaryHeader = true;
100 }
101 writer.printInheritedSummaryHeader(this, classDoc);
102 }
104 /**
105 * {@inheritDoc}
106 */
107 public void writeInheritedMemberSummary(ClassDoc classDoc,
108 ProgramElementDoc method, boolean isFirst, boolean isLast) {
109 writer.printInheritedSummaryMember(this, classDoc, method, isFirst);
110 }
112 /**
113 * Write the inherited methods summary footer for the given class.
114 *
115 * @param classDoc the class the summary belongs to.
116 */
117 public void writeInheritedMemberSummaryFooter(ClassDoc classDoc) {
118 writer.printInheritedSummaryFooter(this, classDoc); ;
119 }
121 /**
122 * Write the header for the method documentation.
123 *
124 * @param classDoc the class that the methods belong to.
125 */
126 public void writeHeader(ClassDoc classDoc, String header) {
127 writer.println();
128 writer.println("<!-- ============ METHOD DETAIL ========== -->");
129 writer.println();
130 writer.anchor("method_detail");
131 writer.printTableHeadingBackground(header);
132 }
134 /**
135 * Write the method header for the given method.
136 *
137 * @param method the method being documented.
138 * @param isFirst the flag to indicate whether or not the method is the
139 * first to be documented.
140 */
141 public void writeMethodHeader(MethodDoc method, boolean isFirst) {
142 if (! isFirst) {
143 writer.printMemberHeader();
144 }
145 writer.println();
146 String erasureAnchor;
147 if ((erasureAnchor = getErasureAnchor(method)) != null) {
148 writer.anchor(erasureAnchor);
149 }
150 writer.anchor(method);
151 writer.h3();
152 writer.print(method.name());
153 writer.h3End();
154 }
156 /**
157 * Write the signature for the given method.
158 *
159 * @param method the method being documented.
160 */
161 public void writeSignature(MethodDoc method) {
162 writer.displayLength = 0;
163 writer.pre();
164 writer.writeAnnotationInfo(method);
165 printModifiers(method);
166 writeTypeParameters(method);
167 printReturnType(method);
168 if (configuration().linksource) {
169 writer.printSrcLink(method, method.name());
170 } else {
171 strong(method.name());
172 }
173 writeParameters(method);
174 writeExceptions(method);
175 writer.preEnd();
176 assert !writer.getMemberDetailsListPrinted();
177 }
179 /**
180 * Write the deprecated output for the given method.
181 *
182 * @param method the method being documented.
183 */
184 public void writeDeprecated(MethodDoc method) {
185 printDeprecated(method);
186 }
188 /**
189 * Write the comments for the given method.
190 *
191 * @param method the method being documented.
192 */
193 public void writeComments(Type holder, MethodDoc method) {
194 ClassDoc holderClassDoc = holder.asClassDoc();
195 if (method.inlineTags().length > 0) {
196 writer.printMemberDetailsListStartTag();
197 if (holder.asClassDoc().equals(classdoc) ||
198 (! (holderClassDoc.isPublic() ||
199 Util.isLinkable(holderClassDoc, configuration())))) {
200 writer.dd();
201 writer.printInlineComment(method);
202 writer.ddEnd();
203 } else {
204 String classlink = writer.codeText(
205 writer.getDocLink(LinkInfoImpl.CONTEXT_METHOD_DOC_COPY,
206 holder.asClassDoc(), method,
207 holder.asClassDoc().isIncluded() ?
208 holder.typeName() : holder.qualifiedTypeName(),
209 false));
210 writer.dd();
211 writer.strongText(holder.asClassDoc().isClass()?
212 "doclet.Description_From_Class":
213 "doclet.Description_From_Interface",
214 classlink);
215 writer.ddEnd();
216 writer.dd();
217 writer.printInlineComment(method);
218 writer.ddEnd();
219 }
220 }
221 }
223 /**
224 * Write the tag output for the given method.
225 *
226 * @param method the method being documented.
227 */
228 public void writeTags(MethodDoc method) {
229 writer.printTags(method);
230 }
232 /**
233 * Write the method footer.
234 */
235 public void writeMethodFooter() {
236 printMemberFooter();
237 }
239 /**
240 * Write the footer for the method documentation.
241 *
242 * @param classDoc the class that the methods belong to.
243 */
244 public void writeFooter(ClassDoc classDoc) {
245 //No footer to write for method documentation
246 }
248 /**
249 * Close the writer.
250 */
251 public void close() throws IOException {
252 writer.close();
253 }
255 public int getMemberKind() {
256 return VisibleMemberMap.METHODS;
257 }
259 public void printSummaryLabel() {
260 writer.printText("doclet.Method_Summary");
261 }
263 public void printTableSummary() {
264 writer.tableIndexSummary(configuration().getText("doclet.Member_Table_Summary",
265 configuration().getText("doclet.Method_Summary"),
266 configuration().getText("doclet.methods")));
267 }
269 public void printSummaryTableHeader(ProgramElementDoc member) {
270 String[] header = new String[] {
271 writer.getModifierTypeHeader(),
272 configuration().getText("doclet.0_and_1",
273 configuration().getText("doclet.Method"),
274 configuration().getText("doclet.Description"))
275 };
276 writer.summaryTableHeader(header, "col");
277 }
279 public void printSummaryAnchor(ClassDoc cd) {
280 writer.anchor("method_summary");
281 }
283 public void printInheritedSummaryAnchor(ClassDoc cd) {
284 writer.anchor("methods_inherited_from_class_" +
285 ConfigurationImpl.getInstance().getClassName(cd));
286 }
288 public void printInheritedSummaryLabel(ClassDoc cd) {
289 String classlink = writer.getPreQualifiedClassLink(
290 LinkInfoImpl.CONTEXT_MEMBER, cd, false);
291 writer.strong();
292 String key = cd.isClass()?
293 "doclet.Methods_Inherited_From_Class" :
294 "doclet.Methods_Inherited_From_Interface";
295 writer.printText(key, classlink);
296 writer.strongEnd();
297 }
299 protected void printSummaryType(ProgramElementDoc member) {
300 MethodDoc meth = (MethodDoc)member;
301 printModifierAndType(meth, meth.returnType());
302 }
304 protected static void printOverridden(HtmlDocletWriter writer,
305 Type overriddenType, MethodDoc method) {
306 if(writer.configuration.nocomment){
307 return;
308 }
309 ClassDoc holderClassDoc = overriddenType.asClassDoc();
310 if (! (holderClassDoc.isPublic() ||
311 Util.isLinkable(holderClassDoc, writer.configuration()))) {
312 //This is an implementation detail that should not be documented.
313 return;
314 }
315 if (overriddenType.asClassDoc().isIncluded() && ! method.isIncluded()) {
316 //The class is included but the method is not. That means that it
317 //is not visible so don't document this.
318 return;
319 }
320 String label = "doclet.Overrides";
321 int context = LinkInfoImpl.CONTEXT_METHOD_OVERRIDES;
323 if (method != null) {
324 if(overriddenType.asClassDoc().isAbstract() && method.isAbstract()){
325 //Abstract method is implemented from abstract class,
326 //not overridden
327 label = "doclet.Specified_By";
328 context = LinkInfoImpl.CONTEXT_METHOD_SPECIFIED_BY;
329 }
330 String overriddenTypeLink = writer.codeText(
331 writer.getLink(new LinkInfoImpl(context, overriddenType)));
332 String name = method.name();
333 writer.dt();
334 writer.strongText(label);
335 writer.dtEnd();
336 writer.dd();
337 String methLink = writer.codeText(
338 writer.getLink(
339 new LinkInfoImpl(LinkInfoImpl.CONTEXT_MEMBER,
340 overriddenType.asClassDoc(),
341 writer.getAnchor(method), name, false)
342 ));
343 writer.printText("doclet.in_class", methLink, overriddenTypeLink);
344 writer.ddEnd();
345 }
346 }
348 /**
349 * Parse the <Code> tag and return the text.
350 */
351 protected String parseCodeTag(String tag){
352 if(tag == null){
353 return "";
354 }
356 String lc = tag.toLowerCase();
357 int begin = lc.indexOf("<code>");
358 int end = lc.indexOf("</code>");
359 if(begin == -1 || end == -1 || end <= begin){
360 return tag;
361 } else {
362 return tag.substring(begin + 6, end);
363 }
364 }
366 protected static void printImplementsInfo(HtmlDocletWriter writer,
367 MethodDoc method) {
368 if(writer.configuration.nocomment){
369 return;
370 }
371 ImplementedMethods implementedMethodsFinder =
372 new ImplementedMethods(method, writer.configuration);
373 MethodDoc[] implementedMethods = implementedMethodsFinder.build();
374 for (int i = 0; i < implementedMethods.length; i++) {
375 MethodDoc implementedMeth = implementedMethods[i];
376 Type intfac = implementedMethodsFinder.getMethodHolder(implementedMeth);
377 String methlink = "";
378 String intfaclink = writer.codeText(
379 writer.getLink(new LinkInfoImpl(
380 LinkInfoImpl.CONTEXT_METHOD_SPECIFIED_BY, intfac)));
381 writer.dt();
382 writer.strongText("doclet.Specified_By");
383 writer.dtEnd();
384 writer.dd();
385 methlink = writer.codeText(writer.getDocLink(
386 LinkInfoImpl.CONTEXT_MEMBER, implementedMeth,
387 implementedMeth.name(), false));
388 writer.printText("doclet.in_interface", methlink, intfaclink);
389 writer.ddEnd();
390 }
392 }
394 protected void printReturnType(MethodDoc method) {
395 Type type = method.returnType();
396 if (type != null) {
397 writer.printLink(new LinkInfoImpl(LinkInfoImpl.CONTEXT_RETURN_TYPE,
398 type));
399 print(' ');
400 }
401 }
403 protected void printNavSummaryLink(ClassDoc cd, boolean link) {
404 if (link) {
405 writer.printHyperLink("", (cd == null)?
406 "method_summary":
407 "methods_inherited_from_class_" +
408 ConfigurationImpl.getInstance().getClassName(cd),
409 ConfigurationImpl.getInstance().getText("doclet.navMethod"));
410 } else {
411 writer.printText("doclet.navMethod");
412 }
413 }
415 protected void printNavDetailLink(boolean link) {
416 if (link) {
417 writer.printHyperLink("", "method_detail",
418 ConfigurationImpl.getInstance().getText("doclet.navMethod"));
419 } else {
420 writer.printText("doclet.navMethod");
421 }
422 }
423 }