1 /*

     2  * Copyright 1997-2006 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  */

    25 

    26 package com.sun.tools.javadoc;

    27 

    28 import com.sun.javadoc.*;

    29 

    30 import com.sun.tools.javac.util.List;

    31 import com.sun.tools.javac.util.ListBuffer;

    32 import com.sun.tools.javac.util.Position;

    33 import com.sun.tools.javac.code.Flags;

    34 import com.sun.tools.javac.code.Type;

    35 import com.sun.tools.javac.code.Symbol;

    36 import com.sun.tools.javac.code.Symbol.*;

    37 import com.sun.tools.javac.tree.JCTree.JCMethodDecl;

    38 

    39 import java.text.CollationKey;

    40 

    41 import java.lang.reflect.Modifier;

    42 

    43 /**

    44  * Represents a method or constructor of a java class.

    45  *

    46  * @since 1.2

    47  * @author Robert Field

    48  * @author Neal Gafter (rewrite)

    49  * @author Scott Seligman (generics, annotations)

    50  */

    51 

    52 public abstract class ExecutableMemberDocImpl

    53         extends MemberDocImpl implements ExecutableMemberDoc {

    54 

    55     protected final MethodSymbol sym;

    56 

    57     /**

    58      * Constructor.

    59      */

    60     public ExecutableMemberDocImpl(DocEnv env, MethodSymbol sym,

    61                                    String rawDocs, JCMethodDecl tree, Position.LineMap lineMap) {

    62         super(env, sym, rawDocs, tree, lineMap);

    63         this.sym = sym;

    64     }

    65 

    66     /**

    67      * Constructor.

    68      */

    69     public ExecutableMemberDocImpl(DocEnv env, MethodSymbol sym) {

    70         this(env, sym, null, null, null);

    71     }

    72 

    73     /**

    74      * Returns the flags in terms of javac's flags

    75      */

    76     protected long getFlags() {

    77         return sym.flags();

    78     }

    79 

    80     /**

    81      * Identify the containing class

    82      */

    83     protected ClassSymbol getContainingClass() {

    84         return sym.enclClass();

    85     }

    86 

    87     /**

    88      * Return true if this method is native

    89      */

    90     public boolean isNative() {

    91         return Modifier.isNative(getModifiers());

    92     }

    93 

    94     /**

    95      * Return true if this method is synchronized

    96      */

    97     public boolean isSynchronized() {

    98         return Modifier.isSynchronized(getModifiers());

    99     }

   100 

   101     /**

   102      * Return true if this method was declared to take a variable number

   103      * of arguments.

   104      */

   105     public boolean isVarArgs() {

   106         return ((sym.flags() & Flags.VARARGS) != 0

   107                 && !env.legacyDoclet);

   108     }

   109 

   110     /**

   111      * Returns true if this field was synthesized by the compiler.

   112      */

   113     public boolean isSynthetic() {

   114         return ((sym.flags() & Flags.SYNTHETIC) != 0);

   115     }

   116 

   117     public boolean isIncluded() {

   118         return containingClass().isIncluded() && env.shouldDocument(sym);

   119     }

   120 

   121     /**

   122      * Return the throws tags in this method.

   123      *

   124      * @return an array of ThrowTagImpl containing all {@code @exception}

   125      * and {@code @throws} tags.

   126      */

   127     public ThrowsTag[] throwsTags() {

   128         return comment().throwsTags();

   129     }

   130 

   131     /**

   132      * Return the param tags in this method, excluding the type

   133      * parameter tags.

   134      *

   135      * @return an array of ParamTagImpl containing all {@code @param} tags.

   136      */

   137     public ParamTag[] paramTags() {

   138         return comment().paramTags();

   139     }

   140 

   141     /**

   142      * Return the type parameter tags in this method.

   143      */

   144     public ParamTag[] typeParamTags() {

   145         return env.legacyDoclet

   146             ? new ParamTag[0]

   147             : comment().typeParamTags();

   148     }

   149 

   150     /**

   151      * Return exceptions this method or constructor throws.

   152      *

   153      * @return an array of ClassDoc[] representing the exceptions

   154      * thrown by this method.

   155      */

   156     public ClassDoc[] thrownExceptions() {

   157         ListBuffer<ClassDocImpl> l = new ListBuffer<ClassDocImpl>();

   158         for (Type ex : sym.type.getThrownTypes()) {

   159             ex = env.types.erasure(ex);

   160             //### Will these casts succeed in the face of static semantic

   161             //### errors in the documented code?

   162             ClassDocImpl cdi = env.getClassDoc((ClassSymbol)ex.tsym);

   163             if (cdi != null) l.append(cdi);

   164         }

   165         return l.toArray(new ClassDocImpl[l.length()]);

   166     }

   167 

   168     /**

   169      * Return exceptions this method or constructor throws.

   170      * Each array element is either a <code>ClassDoc</code> or a

   171      * <code>TypeVariable</code>.

   172      */

   173     public com.sun.javadoc.Type[] thrownExceptionTypes() {

   174         return TypeMaker.getTypes(env, sym.type.getThrownTypes());

   175     }

   176 

   177     /**

   178      * Get argument information.

   179      *

   180      * @see ParameterImpl

   181      *

   182      * @return an array of ParameterImpl, one element per argument

   183      * in the order the arguments are present.

   184      */

   185     public Parameter[] parameters() {

   186         // generate the parameters on the fly:  they're not cached

   187         List<VarSymbol> params = sym.params();

   188         Parameter result[] = new Parameter[params.length()];

   189 

   190         int i = 0;

   191         for (VarSymbol param : params) {

   192             result[i++] = new ParameterImpl(env, param);

   193         }

   194         return result;

   195     }

   196 

   197     /**

   198      * Return the formal type parameters of this method or constructor.

   199      * Return an empty array if there are none.

   200      */

   201     public TypeVariable[] typeParameters() {

   202         if (env.legacyDoclet) {

   203             return new TypeVariable[0];

   204         }

   205         TypeVariable res[] = new TypeVariable[sym.type.getTypeArguments().length()];

   206         TypeMaker.getTypes(env, sym.type.getTypeArguments(), res);

   207         return res;

   208     }

   209 

   210     /**

   211      * Get the signature. It is the parameter list, type is qualified.

   212      * For instance, for a method <code>mymethod(String x, int y)</code>,

   213      * it will return <code>(java.lang.String,int)</code>.

   214      */

   215     public String signature() {

   216         return makeSignature(true);

   217     }

   218 

   219     /**

   220      * Get flat signature.  All types are not qualified.

   221      * Return a String, which is the flat signiture of this member.

   222      * It is the parameter list, type is not qualified.

   223      * For instance, for a method <code>mymethod(String x, int y)</code>,

   224      * it will return <code>(String, int)</code>.

   225      */

   226     public String flatSignature() {

   227         return makeSignature(false);

   228     }

   229 

   230     private String makeSignature(boolean full) {

   231         StringBuffer result = new StringBuffer();

   232         result.append("(");

   233         for (List<Type> types = sym.type.getParameterTypes(); types.nonEmpty(); ) {

   234             Type t = (Type)types.head;

   235             result.append(TypeMaker.getTypeString(env, t, full));

   236             types = types.tail;

   237             if (types.nonEmpty()) {

   238                 result.append(", ");

   239             }

   240         }

   241         if (isVarArgs()) {

   242             int len = result.length();

   243             result.replace(len - 2, len, "...");

   244         }

   245         result.append(")");

   246         return result.toString();

   247     }

   248 

   249     protected String typeParametersString() {

   250         return TypeMaker.typeParametersString(env, sym, true);

   251     }

   252 

   253     /**

   254      * Generate a key for sorting.

   255      */

   256     CollationKey generateKey() {

   257         String k = name() + flatSignature() + typeParametersString();

   258         // ',' and '&' are between '$' and 'a':  normalize to spaces.

   259         k = k.replace(',', ' ').replace('&', ' ');

   260         // System.out.println("COLLATION KEY FOR " + this + " is \"" + k + "\"");

   261         return env.doclocale.collator.getCollationKey(k);

   262     }

   263 

   264     /**

   265      * Return the source position of the entity, or null if

   266      * no position is available.

   267      */

   268     public SourcePosition position() {

   269         if (sym.enclClass().sourcefile == null) return null;

   270         return SourcePositionImpl.make(sym.enclClass().sourcefile.toString(),

   271                                        (tree==null) ? 0 : tree.pos,

   272                                        lineMap);

   273     }

   274 }