Mon, 09 Mar 2009 23:53:41 -0700
Merge
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 */
42 public class MethodWriterImpl extends AbstractExecutableMemberWriter
43 implements MethodWriter, MemberSummaryWriter {
45 private boolean printedSummaryHeader = false;
47 /**
48 * Construct a new MethodWriterImpl.
49 *
50 * @param writer the writer for the class that the methods belong to.
51 * @param classDoc the class being documented.
52 */
53 public MethodWriterImpl(SubWriterHolderWriter writer, ClassDoc classDoc) {
54 super(writer, classDoc);
55 }
57 /**
58 * Construct a new MethodWriterImpl.
59 *
60 * @param writer The writer for the class that the methods belong to.
61 */
62 public MethodWriterImpl(SubWriterHolderWriter writer) {
63 super(writer);
64 }
66 /**
67 * Write the methods summary header for the given class.
68 *
69 * @param classDoc the class the summary belongs to.
70 */
71 public void writeMemberSummaryHeader(ClassDoc classDoc) {
72 printedSummaryHeader = true;
73 writer.println();
74 writer.println("<!-- ========== METHOD SUMMARY =========== -->");
75 writer.println();
76 writer.printSummaryHeader(this, classDoc);
77 }
79 /**
80 * Write the methods summary footer for the given class.
81 *
82 * @param classDoc the class the summary belongs to.
83 */
84 public void writeMemberSummaryFooter(ClassDoc classDoc) {
85 writer.printSummaryFooter(this, classDoc);
86 }
88 /**
89 * Write the inherited methods summary header for the given class.
90 *
91 * @param classDoc the class the summary belongs to.
92 */
93 public void writeInheritedMemberSummaryHeader(ClassDoc classDoc) {
94 if(! printedSummaryHeader){
95 //We don't want inherited summary to not be under heading.
96 writeMemberSummaryHeader(classDoc);
97 writeMemberSummaryFooter(classDoc);
98 printedSummaryHeader = true;
99 }
100 writer.printInheritedSummaryHeader(this, classDoc);
101 }
103 /**
104 * {@inheritDoc}
105 */
106 public void writeInheritedMemberSummary(ClassDoc classDoc,
107 ProgramElementDoc method, boolean isFirst, boolean isLast) {
108 writer.printInheritedSummaryMember(this, classDoc, method, isFirst);
109 }
111 /**
112 * Write the inherited methods summary footer for the given class.
113 *
114 * @param classDoc the class the summary belongs to.
115 */
116 public void writeInheritedMemberSummaryFooter(ClassDoc classDoc) {
117 writer.printInheritedSummaryFooter(this, classDoc); ;
118 }
120 /**
121 * Write the header for the method documentation.
122 *
123 * @param classDoc the class that the methods belong to.
124 */
125 public void writeHeader(ClassDoc classDoc, String header) {
126 writer.println();
127 writer.println("<!-- ============ METHOD DETAIL ========== -->");
128 writer.println();
129 writer.anchor("method_detail");
130 writer.printTableHeadingBackground(header);
131 }
133 /**
134 * Write the method header for the given method.
135 *
136 * @param method the method being documented.
137 * @param isFirst the flag to indicate whether or not the method is the
138 * first to be documented.
139 */
140 public void writeMethodHeader(MethodDoc method, boolean isFirst) {
141 if (! isFirst) {
142 writer.printMemberHeader();
143 }
144 writer.println();
145 String erasureAnchor;
146 if ((erasureAnchor = getErasureAnchor(method)) != null) {
147 writer.anchor(erasureAnchor);
148 }
149 writer.anchor(method);
150 writer.h3();
151 writer.print(method.name());
152 writer.h3End();
153 }
155 /**
156 * Write the signature for the given method.
157 *
158 * @param method the method being documented.
159 */
160 public void writeSignature(MethodDoc method) {
161 writer.displayLength = 0;
162 writer.pre();
163 writer.writeAnnotationInfo(method);
164 printModifiers(method);
165 writeTypeParameters(method);
166 printReturnType(method);
167 if (configuration().linksource) {
168 writer.printSrcLink(method, method.name());
169 } else {
170 strong(method.name());
171 }
172 writeParameters(method);
173 writeExceptions(method);
174 writer.preEnd();
175 assert !writer.getMemberDetailsListPrinted();
176 }
178 /**
179 * Write the deprecated output for the given method.
180 *
181 * @param method the method being documented.
182 */
183 public void writeDeprecated(MethodDoc method) {
184 printDeprecated(method);
185 }
187 /**
188 * Write the comments for the given method.
189 *
190 * @param method the method being documented.
191 */
192 public void writeComments(Type holder, MethodDoc method) {
193 ClassDoc holderClassDoc = holder.asClassDoc();
194 if (method.inlineTags().length > 0) {
195 writer.printMemberDetailsListStartTag();
196 if (holder.asClassDoc().equals(classdoc) ||
197 (! (holderClassDoc.isPublic() ||
198 Util.isLinkable(holderClassDoc, configuration())))) {
199 writer.dd();
200 writer.printInlineComment(method);
201 writer.ddEnd();
202 } else {
203 String classlink = writer.codeText(
204 writer.getDocLink(LinkInfoImpl.CONTEXT_METHOD_DOC_COPY,
205 holder.asClassDoc(), method,
206 holder.asClassDoc().isIncluded() ?
207 holder.typeName() : holder.qualifiedTypeName(),
208 false));
209 writer.dd();
210 writer.strongText(holder.asClassDoc().isClass()?
211 "doclet.Description_From_Class":
212 "doclet.Description_From_Interface",
213 classlink);
214 writer.ddEnd();
215 writer.dd();
216 writer.printInlineComment(method);
217 writer.ddEnd();
218 }
219 }
220 }
222 /**
223 * Write the tag output for the given method.
224 *
225 * @param method the method being documented.
226 */
227 public void writeTags(MethodDoc method) {
228 writer.printTags(method);
229 }
231 /**
232 * Write the method footer.
233 */
234 public void writeMethodFooter() {
235 printMemberFooter();
236 }
238 /**
239 * Write the footer for the method documentation.
240 *
241 * @param classDoc the class that the methods belong to.
242 */
243 public void writeFooter(ClassDoc classDoc) {
244 //No footer to write for method documentation
245 }
247 /**
248 * Close the writer.
249 */
250 public void close() throws IOException {
251 writer.close();
252 }
254 public int getMemberKind() {
255 return VisibleMemberMap.METHODS;
256 }
258 public void printSummaryLabel(ClassDoc cd) {
259 writer.strongText("doclet.Method_Summary");
260 }
262 public void printSummaryAnchor(ClassDoc cd) {
263 writer.anchor("method_summary");
264 }
266 public void printInheritedSummaryAnchor(ClassDoc cd) {
267 writer.anchor("methods_inherited_from_class_" +
268 ConfigurationImpl.getInstance().getClassName(cd));
269 }
271 public void printInheritedSummaryLabel(ClassDoc cd) {
272 String classlink = writer.getPreQualifiedClassLink(
273 LinkInfoImpl.CONTEXT_MEMBER, cd, false);
274 writer.strong();
275 String key = cd.isClass()?
276 "doclet.Methods_Inherited_From_Class" :
277 "doclet.Methods_Inherited_From_Interface";
278 writer.printText(key, classlink);
279 writer.strongEnd();
280 }
282 protected void printSummaryType(ProgramElementDoc member) {
283 MethodDoc meth = (MethodDoc)member;
284 printModifierAndType(meth, meth.returnType());
285 }
287 protected static void printOverridden(HtmlDocletWriter writer,
288 Type overriddenType, MethodDoc method) {
289 if(writer.configuration.nocomment){
290 return;
291 }
292 ClassDoc holderClassDoc = overriddenType.asClassDoc();
293 if (! (holderClassDoc.isPublic() ||
294 Util.isLinkable(holderClassDoc, writer.configuration()))) {
295 //This is an implementation detail that should not be documented.
296 return;
297 }
298 if (overriddenType.asClassDoc().isIncluded() && ! method.isIncluded()) {
299 //The class is included but the method is not. That means that it
300 //is not visible so don't document this.
301 return;
302 }
303 String label = "doclet.Overrides";
304 int context = LinkInfoImpl.CONTEXT_METHOD_OVERRIDES;
306 if (method != null) {
307 if(overriddenType.asClassDoc().isAbstract() && method.isAbstract()){
308 //Abstract method is implemented from abstract class,
309 //not overridden
310 label = "doclet.Specified_By";
311 context = LinkInfoImpl.CONTEXT_METHOD_SPECIFIED_BY;
312 }
313 String overriddenTypeLink = writer.codeText(
314 writer.getLink(new LinkInfoImpl(context, overriddenType)));
315 String name = method.name();
316 writer.dt();
317 writer.strongText(label);
318 writer.dtEnd();
319 writer.dd();
320 String methLink = writer.codeText(
321 writer.getLink(
322 new LinkInfoImpl(LinkInfoImpl.CONTEXT_MEMBER,
323 overriddenType.asClassDoc(),
324 writer.getAnchor(method), name, false)
325 ));
326 writer.printText("doclet.in_class", methLink, overriddenTypeLink);
327 writer.ddEnd();
328 }
329 }
331 /**
332 * Parse the <Code> tag and return the text.
333 */
334 protected String parseCodeTag(String tag){
335 if(tag == null){
336 return "";
337 }
339 String lc = tag.toLowerCase();
340 int begin = lc.indexOf("<code>");
341 int end = lc.indexOf("</code>");
342 if(begin == -1 || end == -1 || end <= begin){
343 return tag;
344 } else {
345 return tag.substring(begin + 6, end);
346 }
347 }
349 protected static void printImplementsInfo(HtmlDocletWriter writer,
350 MethodDoc method) {
351 if(writer.configuration.nocomment){
352 return;
353 }
354 ImplementedMethods implementedMethodsFinder =
355 new ImplementedMethods(method, writer.configuration);
356 MethodDoc[] implementedMethods = implementedMethodsFinder.build();
357 for (int i = 0; i < implementedMethods.length; i++) {
358 MethodDoc implementedMeth = implementedMethods[i];
359 Type intfac = implementedMethodsFinder.getMethodHolder(implementedMeth);
360 String methlink = "";
361 String intfaclink = writer.codeText(
362 writer.getLink(new LinkInfoImpl(
363 LinkInfoImpl.CONTEXT_METHOD_SPECIFIED_BY, intfac)));
364 writer.dt();
365 writer.strongText("doclet.Specified_By");
366 writer.dtEnd();
367 writer.dd();
368 methlink = writer.codeText(writer.getDocLink(
369 LinkInfoImpl.CONTEXT_MEMBER, implementedMeth,
370 implementedMeth.name(), false));
371 writer.printText("doclet.in_interface", methlink, intfaclink);
372 writer.ddEnd();
373 }
375 }
377 protected void printReturnType(MethodDoc method) {
378 Type type = method.returnType();
379 if (type != null) {
380 writer.printLink(new LinkInfoImpl(LinkInfoImpl.CONTEXT_RETURN_TYPE,
381 type));
382 print(' ');
383 }
384 }
386 protected void printNavSummaryLink(ClassDoc cd, boolean link) {
387 if (link) {
388 writer.printHyperLink("", (cd == null)?
389 "method_summary":
390 "methods_inherited_from_class_" +
391 ConfigurationImpl.getInstance().getClassName(cd),
392 ConfigurationImpl.getInstance().getText("doclet.navMethod"));
393 } else {
394 writer.printText("doclet.navMethod");
395 }
396 }
398 protected void printNavDetailLink(boolean link) {
399 if (link) {
400 writer.printHyperLink("", "method_detail",
401 ConfigurationImpl.getInstance().getText("doclet.navMethod"));
402 } else {
403 writer.printText("doclet.navMethod");
404 }
405 }
406 }