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