duke@1: /*
duke@1:  * Copyright 1997-2004 Sun Microsystems, Inc.  All Rights Reserved.
duke@1:  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
duke@1:  *
duke@1:  * This code is free software; you can redistribute it and/or modify it
duke@1:  * under the terms of the GNU General Public License version 2 only, as
duke@1:  * published by the Free Software Foundation.  Sun designates this
duke@1:  * particular file as subject to the "Classpath" exception as provided
duke@1:  * by Sun in the LICENSE file that accompanied this code.
duke@1:  *
duke@1:  * This code is distributed in the hope that it will be useful, but WITHOUT
duke@1:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
duke@1:  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
duke@1:  * version 2 for more details (a copy is included in the LICENSE file that
duke@1:  * accompanied this code).
duke@1:  *
duke@1:  * You should have received a copy of the GNU General Public License version
duke@1:  * 2 along with this work; if not, write to the Free Software Foundation,
duke@1:  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
duke@1:  *
duke@1:  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
duke@1:  * CA 95054 USA or visit www.sun.com if you need additional information or
duke@1:  * have any questions.
duke@1:  */
duke@1: 
duke@1: package com.sun.tools.doclets.formats.html;
duke@1: 
bpatel@233: import java.io.*;
bpatel@233: 
bpatel@233: import com.sun.javadoc.*;
duke@1: import com.sun.tools.doclets.internal.toolkit.*;
duke@1: import com.sun.tools.doclets.internal.toolkit.util.*;
duke@1: import com.sun.tools.doclets.internal.toolkit.taglets.*;
duke@1: 
duke@1: /**
duke@1:  * Writes method documentation in HTML format.
duke@1:  *
duke@1:  * @author Robert Field
duke@1:  * @author Atul M Dambalkar
duke@1:  * @author Jamie Ho (rewrite)
duke@1:  */
duke@1: public class MethodWriterImpl extends AbstractExecutableMemberWriter
duke@1:         implements MethodWriter, MemberSummaryWriter {
duke@1: 
duke@1:     private boolean printedSummaryHeader = false;
duke@1: 
duke@1:     /**
duke@1:      * Construct a new MethodWriterImpl.
duke@1:      *
duke@1:      * @param writer the writer for the class that the methods belong to.
duke@1:      * @param classDoc the class being documented.
duke@1:      */
duke@1:     public MethodWriterImpl(SubWriterHolderWriter writer, ClassDoc classDoc) {
duke@1:         super(writer, classDoc);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Construct a new MethodWriterImpl.
duke@1:      *
duke@1:      * @param writer The writer for the class that the methods belong to.
duke@1:      */
duke@1:     public MethodWriterImpl(SubWriterHolderWriter writer) {
duke@1:         super(writer);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the methods summary header for the given class.
duke@1:      *
duke@1:      * @param classDoc the class the summary belongs to.
duke@1:      */
duke@1:     public void writeMemberSummaryHeader(ClassDoc classDoc) {
duke@1:         printedSummaryHeader = true;
duke@1:         writer.println();
duke@1:         writer.println("<!-- ========== METHOD SUMMARY =========== -->");
duke@1:         writer.println();
duke@1:         writer.printSummaryHeader(this, classDoc);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the methods summary footer for the given class.
duke@1:      *
duke@1:      * @param classDoc the class the summary belongs to.
duke@1:      */
duke@1:     public void writeMemberSummaryFooter(ClassDoc classDoc) {
duke@1:         writer.printSummaryFooter(this, classDoc);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the inherited methods summary header for the given class.
duke@1:      *
duke@1:      * @param classDoc the class the summary belongs to.
duke@1:      */
duke@1:     public void writeInheritedMemberSummaryHeader(ClassDoc classDoc) {
duke@1:         if(! printedSummaryHeader){
duke@1:             //We don't want inherited summary to not be under heading.
duke@1:             writeMemberSummaryHeader(classDoc);
duke@1:             writeMemberSummaryFooter(classDoc);
duke@1:             printedSummaryHeader = true;
duke@1:         }
duke@1:         writer.printInheritedSummaryHeader(this, classDoc);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * {@inheritDoc}
duke@1:      */
duke@1:     public void writeInheritedMemberSummary(ClassDoc classDoc,
duke@1:         ProgramElementDoc method, boolean isFirst, boolean isLast) {
duke@1:         writer.printInheritedSummaryMember(this, classDoc, method, isFirst);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the inherited methods summary footer for the given class.
duke@1:      *
duke@1:      * @param classDoc the class the summary belongs to.
duke@1:      */
duke@1:     public void writeInheritedMemberSummaryFooter(ClassDoc classDoc) {
duke@1:         writer.printInheritedSummaryFooter(this, classDoc);        ;
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the header for the method documentation.
duke@1:      *
duke@1:      * @param classDoc the class that the methods belong to.
duke@1:      */
duke@1:     public void writeHeader(ClassDoc classDoc, String header) {
duke@1:         writer.println();
duke@1:         writer.println("<!-- ============ METHOD DETAIL ========== -->");
duke@1:         writer.println();
duke@1:         writer.anchor("method_detail");
duke@1:         writer.printTableHeadingBackground(header);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the method header for the given method.
duke@1:      *
duke@1:      * @param method the method being documented.
duke@1:      * @param isFirst the flag to indicate whether or not the method is the
duke@1:      *        first to be documented.
duke@1:      */
duke@1:     public void writeMethodHeader(MethodDoc method, boolean isFirst) {
duke@1:         if (! isFirst) {
duke@1:             writer.printMemberHeader();
duke@1:         }
duke@1:         writer.println();
duke@1:         String erasureAnchor;
duke@1:         if ((erasureAnchor = getErasureAnchor(method)) != null) {
duke@1:             writer.anchor(erasureAnchor);
duke@1:         }
duke@1:         writer.anchor(method);
duke@1:         writer.h3();
duke@1:         writer.print(method.name());
duke@1:         writer.h3End();
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the signature for the given method.
duke@1:      *
duke@1:      * @param method the method being documented.
duke@1:      */
duke@1:     public void writeSignature(MethodDoc method) {
duke@1:         writer.displayLength = 0;
duke@1:         writer.pre();
duke@1:         writer.writeAnnotationInfo(method);
duke@1:         printModifiers(method);
duke@1:         writeTypeParameters(method);
duke@1:         printReturnType(method);
duke@1:         if (configuration().linksource) {
duke@1:             writer.printSrcLink(method, method.name());
duke@1:         } else {
bpatel@182:             strong(method.name());
duke@1:         }
duke@1:         writeParameters(method);
duke@1:         writeExceptions(method);
duke@1:         writer.preEnd();
bpatel@233:         assert !writer.getMemberDetailsListPrinted();
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the deprecated output for the given method.
duke@1:      *
duke@1:      * @param method the method being documented.
duke@1:      */
duke@1:     public void writeDeprecated(MethodDoc method) {
bpatel@233:         printDeprecated(method);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the comments for the given method.
duke@1:      *
duke@1:      * @param method the method being documented.
duke@1:      */
duke@1:     public void writeComments(Type holder, MethodDoc method) {
duke@1:         ClassDoc holderClassDoc = holder.asClassDoc();
duke@1:         if (method.inlineTags().length > 0) {
bpatel@233:             writer.printMemberDetailsListStartTag();
duke@1:             if (holder.asClassDoc().equals(classdoc) ||
duke@1:                 (! (holderClassDoc.isPublic() ||
duke@1:                     Util.isLinkable(holderClassDoc, configuration())))) {
duke@1:                 writer.dd();
duke@1:                 writer.printInlineComment(method);
bpatel@233:                 writer.ddEnd();
duke@1:             } else {
duke@1:                 String classlink = writer.codeText(
duke@1:                     writer.getDocLink(LinkInfoImpl.CONTEXT_METHOD_DOC_COPY,
duke@1:                         holder.asClassDoc(), method,
duke@1:                         holder.asClassDoc().isIncluded() ?
duke@1:                             holder.typeName() : holder.qualifiedTypeName(),
duke@1:                         false));
duke@1:                 writer.dd();
bpatel@182:                 writer.strongText(holder.asClassDoc().isClass()?
duke@1:                         "doclet.Description_From_Class":
duke@1:                         "doclet.Description_From_Interface",
duke@1:                     classlink);
duke@1:                 writer.ddEnd();
duke@1:                 writer.dd();
duke@1:                 writer.printInlineComment(method);
bpatel@233:                 writer.ddEnd();
duke@1:             }
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the tag output for the given method.
duke@1:      *
duke@1:      * @param method the method being documented.
duke@1:      */
duke@1:     public void writeTags(MethodDoc method) {
duke@1:         writer.printTags(method);
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the method footer.
duke@1:      */
duke@1:     public void writeMethodFooter() {
bpatel@233:         printMemberFooter();
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Write the footer for the method documentation.
duke@1:      *
duke@1:      * @param classDoc the class that the methods belong to.
duke@1:      */
duke@1:     public void writeFooter(ClassDoc classDoc) {
duke@1:         //No footer to write for method documentation
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Close the writer.
duke@1:      */
duke@1:     public void close() throws IOException {
duke@1:         writer.close();
duke@1:     }
duke@1: 
duke@1:     public int getMemberKind() {
duke@1:         return VisibleMemberMap.METHODS;
duke@1:     }
duke@1: 
duke@1:     public void printSummaryLabel(ClassDoc cd) {
bpatel@182:         writer.strongText("doclet.Method_Summary");
duke@1:     }
duke@1: 
duke@1:     public void printSummaryAnchor(ClassDoc cd) {
duke@1:         writer.anchor("method_summary");
duke@1:     }
duke@1: 
duke@1:     public void printInheritedSummaryAnchor(ClassDoc cd) {
duke@1:         writer.anchor("methods_inherited_from_class_" +
duke@1:             ConfigurationImpl.getInstance().getClassName(cd));
duke@1:     }
duke@1: 
duke@1:     public void printInheritedSummaryLabel(ClassDoc cd) {
duke@1:         String classlink = writer.getPreQualifiedClassLink(
duke@1:             LinkInfoImpl.CONTEXT_MEMBER, cd, false);
bpatel@182:         writer.strong();
duke@1:         String key = cd.isClass()?
duke@1:             "doclet.Methods_Inherited_From_Class" :
duke@1:             "doclet.Methods_Inherited_From_Interface";
duke@1:         writer.printText(key, classlink);
bpatel@182:         writer.strongEnd();
duke@1:     }
duke@1: 
duke@1:     protected void printSummaryType(ProgramElementDoc member) {
duke@1:         MethodDoc meth = (MethodDoc)member;
duke@1:         printModifierAndType(meth, meth.returnType());
duke@1:     }
duke@1: 
duke@1:     protected static void printOverridden(HtmlDocletWriter writer,
duke@1:             Type overriddenType, MethodDoc method) {
duke@1:         if(writer.configuration.nocomment){
duke@1:             return;
duke@1:         }
duke@1:         ClassDoc holderClassDoc = overriddenType.asClassDoc();
duke@1:         if (! (holderClassDoc.isPublic() ||
duke@1:             Util.isLinkable(holderClassDoc, writer.configuration()))) {
duke@1:             //This is an implementation detail that should not be documented.
duke@1:             return;
duke@1:         }
duke@1:         if (overriddenType.asClassDoc().isIncluded() && ! method.isIncluded()) {
duke@1:             //The class is included but the method is not.  That means that it
duke@1:             //is not visible so don't document this.
duke@1:             return;
duke@1:         }
duke@1:         String label = "doclet.Overrides";
duke@1:         int context = LinkInfoImpl.CONTEXT_METHOD_OVERRIDES;
duke@1: 
duke@1:         if (method != null) {
duke@1:             if(overriddenType.asClassDoc().isAbstract() && method.isAbstract()){
duke@1:                 //Abstract method is implemented from abstract class,
duke@1:                 //not overridden
duke@1:                 label = "doclet.Specified_By";
duke@1:                 context = LinkInfoImpl.CONTEXT_METHOD_SPECIFIED_BY;
duke@1:             }
duke@1:             String overriddenTypeLink = writer.codeText(
duke@1:                 writer.getLink(new LinkInfoImpl(context, overriddenType)));
duke@1:             String name = method.name();
duke@1:             writer.dt();
bpatel@182:             writer.strongText(label);
bpatel@233:             writer.dtEnd();
duke@1:             writer.dd();
duke@1:             String methLink = writer.codeText(
duke@1:                 writer.getLink(
duke@1:                     new LinkInfoImpl(LinkInfoImpl.CONTEXT_MEMBER,
duke@1:                         overriddenType.asClassDoc(),
duke@1:                         writer.getAnchor(method), name, false)
duke@1:                 ));
duke@1:             writer.printText("doclet.in_class", methLink, overriddenTypeLink);
bpatel@233:             writer.ddEnd();
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     /**
duke@1:      * Parse the &lt;Code&gt; tag and return the text.
duke@1:      */
duke@1:     protected String parseCodeTag(String tag){
duke@1:         if(tag == null){
duke@1:             return "";
duke@1:         }
duke@1: 
duke@1:         String lc = tag.toLowerCase();
duke@1:         int begin = lc.indexOf("<code>");
duke@1:         int end = lc.indexOf("</code>");
duke@1:         if(begin == -1 || end == -1 || end <= begin){
duke@1:             return tag;
duke@1:         } else {
duke@1:             return tag.substring(begin + 6, end);
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     protected static void printImplementsInfo(HtmlDocletWriter writer,
duke@1:             MethodDoc method) {
duke@1:         if(writer.configuration.nocomment){
duke@1:             return;
duke@1:         }
duke@1:         ImplementedMethods implementedMethodsFinder =
duke@1:             new ImplementedMethods(method, writer.configuration);
duke@1:         MethodDoc[] implementedMethods = implementedMethodsFinder.build();
duke@1:         for (int i = 0; i < implementedMethods.length; i++) {
duke@1:             MethodDoc implementedMeth = implementedMethods[i];
duke@1:             Type intfac = implementedMethodsFinder.getMethodHolder(implementedMeth);
duke@1:             String methlink = "";
duke@1:             String intfaclink = writer.codeText(
duke@1:                 writer.getLink(new LinkInfoImpl(
duke@1:                     LinkInfoImpl.CONTEXT_METHOD_SPECIFIED_BY, intfac)));
duke@1:             writer.dt();
bpatel@182:             writer.strongText("doclet.Specified_By");
bpatel@233:             writer.dtEnd();
duke@1:             writer.dd();
duke@1:             methlink = writer.codeText(writer.getDocLink(
duke@1:                 LinkInfoImpl.CONTEXT_MEMBER, implementedMeth,
duke@1:                 implementedMeth.name(), false));
duke@1:             writer.printText("doclet.in_interface", methlink, intfaclink);
bpatel@233:             writer.ddEnd();
duke@1:         }
duke@1: 
duke@1:     }
duke@1: 
duke@1:     protected void printReturnType(MethodDoc method) {
duke@1:         Type type = method.returnType();
duke@1:         if (type != null) {
duke@1:             writer.printLink(new LinkInfoImpl(LinkInfoImpl.CONTEXT_RETURN_TYPE,
duke@1:                 type));
duke@1:             print(' ');
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     protected void printNavSummaryLink(ClassDoc cd, boolean link) {
duke@1:         if (link) {
duke@1:             writer.printHyperLink("", (cd == null)?
duke@1:                 "method_summary":
duke@1:                 "methods_inherited_from_class_" +
duke@1:                 ConfigurationImpl.getInstance().getClassName(cd),
duke@1:                 ConfigurationImpl.getInstance().getText("doclet.navMethod"));
duke@1:         } else {
duke@1:             writer.printText("doclet.navMethod");
duke@1:         }
duke@1:     }
duke@1: 
duke@1:     protected void printNavDetailLink(boolean link) {
duke@1:         if (link) {
duke@1:             writer.printHyperLink("", "method_detail",
duke@1:                 ConfigurationImpl.getInstance().getText("doclet.navMethod"));
duke@1:         } else {
duke@1:             writer.printText("doclet.navMethod");
duke@1:         }
duke@1:     }
duke@1: }