1 /**
2 * Redistribution and use of this software and associated documentation ("Software"), with or
3 * without modification, are permitted provided that the following conditions are met:
4 *
5 * 1. Redistributions of source code must retain copyright statements and notices. Redistributions
6 * must also contain a copy of this document.
7 *
8 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of
9 * conditions and the following disclaimer in the documentation and/or other materials provided with
10 * the distribution.
11 *
12 * 3. The name "Exolab" must not be used to endorse or promote products derived from this Software
13 * without prior written permission of Intalio, Inc. For written permission, please contact
14 * info@exolab.org.
15 *
16 * 4. Products derived from this Software may not be called "Exolab" nor may "Exolab" appear in
17 * their names without prior written permission of Intalio, Inc. Exolab is a registered trademark of
18 * Intalio, Inc.
19 *
20 * 5. Due credit should be given to the Exolab Project (http://www.exolab.org/).
21 *
22 * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR
23 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
24 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTALIO, INC. OR ITS
25 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
29 * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 *
31 * Copyright 1999 (C) Intalio, Inc. All Rights Reserved.
32 */
33 package org.exolab.javasource;
34
35 /**
36 * A descriptor for a JavaDoc comment.
37 *
38 * @author <a href="mailto:keith AT kvisco DOT com">Keith Visco</a>
39 * @version $Revision$ $Date: 2003-03-03 00:05:44 -0700 (Mon, 03 Mar 2003) $
40 */
41 public final class JDocDescriptor {
42 // --------------------------------------------------------------------------
43
44 /** The default version string, broken into parts so CVS does not expand it. */
45 public static final String DEFAULT_VERSION = "$" + "Revision" + "$ $" + "Date" + "$";
46
47 // These are listed in order of how they should appear in a JavaDoc
48 // list, so the numbers are important...see #compareTo
49
50 /** The param descriptor (param). */
51 public static final short PARAM = 0;
52
53 /** The exception descriptor (exception). */
54 public static final short EXCEPTION = 1;
55
56 /** The return descriptor (return). */
57 public static final short RETURN = 2;
58
59 /** The author descriptor. */
60 public static final short AUTHOR = 3;
61
62 /** The version descriptor (version). */
63 public static final short VERSION = 4;
64
65 /** The reference descriptor (see). */
66 public static final short REFERENCE = 5;
67
68 // --------------------------------------------------------------------------
69
70 /** A description string for the object being described. */
71 private String _description = null;
72
73 /** The name of this JDocDescriptor. */
74 private String _name = null;
75
76 /**
77 * The type of JDocDescriptor, one of {@link #PARAM}, {@link #EXCEPTION}, {@link #RETURN},
78 * {@link #AUTHOR}, {@link #VERSION}, {@link #REFERENCE}.
79 */
80 private short _type = -1;
81
82 // --------------------------------------------------------------------------
83
84 /**
85 * Creates a new JDocDescriptor.
86 *
87 * @param type The type of JDocDescriptor (e.g., {@link #REFERENCE}.
88 */
89 private JDocDescriptor(final short type) {
90 _type = type;
91 }
92
93 /**
94 * Creates a new JDocDescriptor.
95 *
96 * @param type The type of JDocDescriptor (e.g., {@link #REFERENCE}.
97 * @param name The name string for this descriptor.
98 * @param desc The description string for this descriptor.
99 */
100 private JDocDescriptor(final short type, final String name, final String desc) {
101 _type = type;
102 _name = name;
103 _description = desc;
104 }
105
106 // --------------------------------------------------------------------------
107
108 /**
109 * Compares the type of this JDocDescriptor with the given descriptor. Enables sorting of
110 * descriptors.
111 *
112 * @param jdd A JDocDescriptor to be compared to this one.
113 * @return 0 if the two descriptor types are equal, 1 if the type of this descriptor is greater
114 * than the given descriptor, or -1 if the type of this descriptor is less than the given
115 * descriptor.
116 */
117 protected short compareTo(final JDocDescriptor jdd) {
118 short jddType = jdd.getType();
119
120 if (jddType == this._type) {
121 return 0;
122 }
123
124 // The ordering is as follows
125 // #param
126 // #exception
127 // #author
128 // #version
129 // #see (reference)
130 //
131 return (short) ((jddType < this._type) ? 1 : -1);
132 }
133
134 /**
135 * Creates a new, empty @author JavaDoc descriptor.
136 *
137 * @return The new JDocDescriptor.
138 */
139 public static JDocDescriptor createAuthorDesc() {
140 return new JDocDescriptor(AUTHOR);
141 }
142
143 /**
144 * Creates a new @author JavaDoc descriptor with the provided author name string.
145 *
146 * @param name The author name string.
147 * @return The new JDocDescriptor.
148 */
149 public static JDocDescriptor createAuthorDesc(final String name) {
150 return new JDocDescriptor(AUTHOR, name, null);
151 }
152
153 /**
154 * Creates a new, empty @exception JavaDoc descriptor.
155 *
156 * @return The new JDocDescriptor.
157 */
158 public static JDocDescriptor createExceptionDesc() {
159 return new JDocDescriptor(EXCEPTION);
160 }
161
162 /**
163 * Creates a new @exception JavaDoc descriptor with a given exception name and a description
164 * of when the exception is thrown.
165 *
166 * @param name The exception name.
167 * @param desc The description of when the exception is thrown.
168 * @return The new JDocDescriptor.
169 */
170 public static JDocDescriptor createExceptionDesc(final String name, final String desc) {
171 return new JDocDescriptor(EXCEPTION, name, desc);
172 }
173
174 /**
175 * Creates a new, empty @param JavaDoc descriptor.
176 *
177 * @return The new JDocDescriptor.
178 */
179 public static JDocDescriptor createParamDesc() {
180 return new JDocDescriptor(PARAM);
181 }
182
183 /**
184 * Creates a new @param JavaDoc descriptor with the given parameter name and description.
185 *
186 * @param name The param name.
187 * @param desc The param description string.
188 * @return The new JDocDescriptor.
189 */
190 public static JDocDescriptor createParamDesc(final String name, final String desc) {
191 return new JDocDescriptor(PARAM, name, desc);
192 }
193
194 /**
195 * Creates a new, empty @reference JavaDoc descriptor.
196 *
197 * @return The new JDocDescriptor.
198 */
199 public static JDocDescriptor createReferenceDesc() {
200 return new JDocDescriptor(REFERENCE);
201 }
202
203 /**
204 * Creates a new @reference JavaDoc descriptor with the provided reference string.
205 *
206 * @param name The reference name string.
207 * @return The new JDocDescriptor.
208 */
209 public static JDocDescriptor createReferenceDesc(final String name) {
210 return new JDocDescriptor(REFERENCE, name, null);
211 }
212
213 /**
214 * Creates a new, empty @return JavaDoc descriptor.
215 *
216 * @return The new JDocDescriptor.
217 */
218 public static JDocDescriptor createReturnDesc() {
219 return new JDocDescriptor(RETURN);
220 }
221
222 /**
223 * Creates a new @return JavaDoc descriptor with the provided description of what is
224 * returned.
225 *
226 * @param desc The return description.
227 * @return The new JDocDescriptor.
228 */
229 public static JDocDescriptor createReturnDesc(final String desc) {
230 return new JDocDescriptor(RETURN, null, desc);
231 }
232
233 /**
234 * Creates a new, empty @version JavaDoc descriptor.
235 *
236 * @return The new JDocDescriptor.
237 */
238 public static JDocDescriptor createVersionDesc() {
239 return new JDocDescriptor(VERSION);
240 }
241
242 /**
243 * Creates a new @version JavaDoc descriptor with the provided version string.
244 *
245 * @param version The version string.
246 * @return The new JDocDescriptor.
247 */
248 public static JDocDescriptor createVersionDesc(final String version) {
249 return new JDocDescriptor(VERSION, null, version);
250 }
251
252 /**
253 * Returns the description String.
254 *
255 * @return The description string.
256 */
257 public String getDescription() {
258 return _description;
259 }
260
261 /**
262 * Returns the name of the object being described. This is valid for the following fields:
263 * <ul>
264 * <li>author</li>
265 * <li>exception</li>
266 * <li>param</li>
267 * <li>see</li>
268 * </ul>
269 *
270 * @return The name of the object being described.
271 */
272 public String getName() {
273 return _name;
274 }
275
276 /**
277 * Returns the type of this JDocDescriptor.
278 *
279 * @return The type of this JDocDescriptor.
280 */
281 public short getType() {
282 return _type;
283 }
284
285 /**
286 * Sets the description String for this descriptor.
287 *
288 * @param desc The description of the object being described.
289 */
290 public void setDescription(final String desc) {
291 _description = desc;
292 }
293
294
295 /**
296 * Sets the name value of the JavaDoc field. This is only valid for the following fields:
297 * <ul>
298 * <li>author</li>
299 * <li>exception</li>
300 * <li>param</li>
301 * <li>see</li>
302 * </ul>
303 *
304 * @param name The name value of the JavaDoc field.
305 */
306 public void setName(final String name) {
307 _name = name;
308 }
309
310 // --------------------------------------------------------------------------
311
312 /**
313 * {@inheritDoc}
314 */
315 public String toString() {
316 StringBuilder sb = new StringBuilder();
317 boolean allowName = true;
318 switch (_type) {
319 case AUTHOR:
320 sb.append("@author");
321 break;
322 case EXCEPTION:
323 sb.append("@throws");
324 break;
325 case PARAM:
326 sb.append("@param");
327 break;
328 case REFERENCE:
329 sb.append("@see");
330 break;
331 case RETURN:
332 sb.append("@return");
333 break;
334 case VERSION:
335 allowName = false;
336 sb.append("@version");
337 break;
338 default:
339 break;
340 }
341
342 if ((_name != null) && allowName) {
343 sb.append(' ');
344 sb.append(_name);
345 }
346
347 if (_description != null) {
348 sb.append(' ');
349 sb.append(_description);
350 }
351
352 return sb.toString();
353 }
354
355 // --------------------------------------------------------------------------
356 }