Thu, 18 Sep 2008 18:39:44 -0700
6744408: Extra ouput is appearing in stderr
Reviewed-by: bpatel
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 */
26 package com.sun.tools.javadoc;
28 import com.sun.javadoc.*;
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;
39 import java.text.CollationKey;
41 import java.lang.reflect.Modifier;
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 */
52 public abstract class ExecutableMemberDocImpl
53 extends MemberDocImpl implements ExecutableMemberDoc {
55 protected final MethodSymbol sym;
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 }
66 /**
67 * Constructor.
68 */
69 public ExecutableMemberDocImpl(DocEnv env, MethodSymbol sym) {
70 this(env, sym, null, null, null);
71 }
73 /**
74 * Returns the flags in terms of javac's flags
75 */
76 protected long getFlags() {
77 return sym.flags();
78 }
80 /**
81 * Identify the containing class
82 */
83 protected ClassSymbol getContainingClass() {
84 return sym.enclClass();
85 }
87 /**
88 * Return true if this method is native
89 */
90 public boolean isNative() {
91 return Modifier.isNative(getModifiers());
92 }
94 /**
95 * Return true if this method is synchronized
96 */
97 public boolean isSynchronized() {
98 return Modifier.isSynchronized(getModifiers());
99 }
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 }
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 }
117 public boolean isIncluded() {
118 return containingClass().isIncluded() && env.shouldDocument(sym);
119 }
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 }
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 }
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 }
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 }
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 }
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()];
190 int i = 0;
191 for (VarSymbol param : params) {
192 result[i++] = new ParameterImpl(env, param);
193 }
194 return result;
195 }
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 }
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 }
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 }
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 = 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 }
249 protected String typeParametersString() {
250 return TypeMaker.typeParametersString(env, sym, true);
251 }
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 }
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 }