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  */

    25 

    26 package com.sun.tools.javadoc.main;

    27 

    28 import java.lang.reflect.Modifier;

    29 import java.text.CollationKey;

    30 

    31 import com.sun.javadoc.*;

    32 

    33 import com.sun.source.util.TreePath;

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

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

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

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

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

    39 

    40 /**

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

    42  *

    43  *  <p><b>This is NOT part of any supported API.

    44  *  If you write code that depends on this, you do so at your own risk.

    45  *  This code and its internal interfaces are subject to change or

    46  *  deletion without notice.</b>

    47  *

    48  * @since 1.2

    49  * @author Robert Field

    50  * @author Neal Gafter (rewrite)

    51  * @author Scott Seligman (generics, annotations)

    52  */

    53 

    54 public abstract class ExecutableMemberDocImpl

    55         extends MemberDocImpl implements ExecutableMemberDoc {

    56 

    57     protected final MethodSymbol sym;

    58 

    59     /**

    60      * Constructor.

    61      */

    62     public ExecutableMemberDocImpl(DocEnv env, MethodSymbol sym, TreePath treePath) {

    63         super(env, sym, treePath);

    64         this.sym = sym;

    65     }

    66 

    67     /**

    68      * Constructor.

    69      */

    70     public ExecutableMemberDocImpl(DocEnv env, MethodSymbol sym) {

    71         this(env, sym, null);

    72     }

    73 

    74     /**

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

    76      */

    77     protected long getFlags() {

    78         return sym.flags();

    79     }

    80 

    81     /**

    82      * Identify the containing class

    83      */

    84     protected ClassSymbol getContainingClass() {

    85         return sym.enclClass();

    86     }

    87 

    88     /**

    89      * Return true if this method is native

    90      */

    91     public boolean isNative() {

    92         return Modifier.isNative(getModifiers());

    93     }

    94 

    95     /**

    96      * Return true if this method is synchronized

    97      */

    98     public boolean isSynchronized() {

    99         return Modifier.isSynchronized(getModifiers());

   100     }

   101 

   102     /**

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

   104      * of arguments.

   105      */

   106     public boolean isVarArgs() {

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

   108                 && !env.legacyDoclet);

   109     }

   110 

   111     /**

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

   113      */

   114     public boolean isSynthetic() {

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

   116     }

   117 

   118     public boolean isIncluded() {

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

   120     }

   121 

   122     /**

   123      * Return the throws tags in this method.

   124      *

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

   126      * and {@code @throws} tags.

   127      */

   128     public ThrowsTag[] throwsTags() {

   129         return comment().throwsTags();

   130     }

   131 

   132     /**

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

   134      * parameter tags.

   135      *

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

   137      */

   138     public ParamTag[] paramTags() {

   139         return comment().paramTags();

   140     }

   141 

   142     /**

   143      * Return the type parameter tags in this method.

   144      */

   145     public ParamTag[] typeParamTags() {

   146         return env.legacyDoclet

   147             ? new ParamTag[0]

   148             : comment().typeParamTags();

   149     }

   150 

   151     /**

   152      * Return exceptions this method or constructor throws.

   153      *

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

   155      * thrown by this method.

   156      */

   157     public ClassDoc[] thrownExceptions() {

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

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

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

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

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

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

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

   165         }

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

   167     }

   168 

   169     /**

   170      * Return exceptions this method or constructor throws.

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

   172      * <code>TypeVariable</code>.

   173      */

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

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

   176     }

   177 

   178     /**

   179      * Get argument information.

   180      *

   181      * @see ParameterImpl

   182      *

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

   184      * in the order the arguments are present.

   185      */

   186     public Parameter[] parameters() {

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

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

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

   190 

   191         int i = 0;

   192         for (VarSymbol param : params) {

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

   194         }

   195         return result;

   196     }

   197 

   198     /**

   199      * Get the receiver type of this executable element.

   200      *

   201      * @return the receiver type of this executable element.

   202      * @since 1.8

   203      */

   204     public com.sun.javadoc.Type receiverType() {

   205         Type recvtype = sym.type.asMethodType().recvtype;

   206         return (recvtype != null) ? TypeMaker.getType(env, recvtype, false, true) : null;

   207     }

   208 

   209     /**

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

   211      * Return an empty array if there are none.

   212      */

   213     public TypeVariable[] typeParameters() {

   214         if (env.legacyDoclet) {

   215             return new TypeVariable[0];

   216         }

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

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

   219         return res;

   220     }

   221 

   222     /**

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

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

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

   226      */

   227     public String signature() {

   228         return makeSignature(true);

   229     }

   230 

   231     /**

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

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

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

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

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

   237      */

   238     public String flatSignature() {

   239         return makeSignature(false);

   240     }

   241 

   242     private String makeSignature(boolean full) {

   243         StringBuilder result = new StringBuilder();

   244         result.append("(");

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

   246             Type t = types.head;

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

   248             types = types.tail;

   249             if (types.nonEmpty()) {

   250                 result.append(", ");

   251             }

   252         }

   253         if (isVarArgs()) {

   254             int len = result.length();

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

   256         }

   257         result.append(")");

   258         return result.toString();

   259     }

   260 

   261     protected String typeParametersString() {

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

   263     }

   264 

   265     /**

   266      * Generate a key for sorting.

   267      */

   268     @Override

   269     CollationKey generateKey() {

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

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

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

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

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

   275     }

   276 

   277     /**

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

   279      * no position is available.

   280      */

   281     @Override

   282     public SourcePosition position() {

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

   284         return SourcePositionImpl.make(sym.enclClass().sourcefile,

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

   286                                        lineMap);

   287     }

   288 }