001: /**
002: * Redistribution and use of this software and associated documentation
003: * ("Software"), with or without modification, are permitted provided
004: * that the following conditions are met:
005: *
006: * 1. Redistributions of source code must retain copyright
007: * statements and notices. Redistributions must also contain a
008: * copy of this document.
009: *
010: * 2. Redistributions in binary form must reproduce the
011: * above copyright notice, this list of conditions and the
012: * following disclaimer in the documentation and/or other
013: * materials provided with the distribution.
014: *
015: * 3. The name "Exolab" must not be used to endorse or promote
016: * products derived from this Software without prior written
017: * permission of Intalio, Inc. For written permission,
018: * please contact info@exolab.org.
019: *
020: * 4. Products derived from this Software may not be called "Exolab"
021: * nor may "Exolab" appear in their names without prior written
022: * permission of Intalio, Inc. Exolab is a registered
023: * trademark of Intalio, Inc.
024: *
025: * 5. Due credit should be given to the Exolab Project
026: * (http://www.exolab.org/).
027: *
028: * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS
029: * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
030: * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
031: * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
032: * INTALIO, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
033: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
034: * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
035: * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
036: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
037: * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
038: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
039: * OF THE POSSIBILITY OF SUCH DAMAGE.
040: *
041: * Copyright 1999 (C) Intalio, Inc. All Rights Reserved.
042: */package org.exolab.javasource;
043:
044: /**
045: * A descriptor for a JavaDoc comment.
046: *
047: * @author <a href="mailto:keith AT kvisco DOT com">Keith Visco</a>
048: * @version $Revision: 6669 $ $Date: 2003-03-03 00:05:44 -0700 (Mon, 03 Mar 2003) $
049: */
050: public final class JDocDescriptor {
051: //--------------------------------------------------------------------------
052:
053: /** The default version string, broken into parts so CVS does not expand it. */
054: public static final String DEFAULT_VERSION = "$" + "Revision"
055: + "$ $" + "Date" + "$";
056:
057: // These are listed in order of how they should appear in a JavaDoc
058: // list, so the numbers are important...see #compareTo
059:
060: /** The param descriptor (param). */
061: public static final short PARAM = 0;
062:
063: /** The exception descriptor (exception). */
064: public static final short EXCEPTION = 1;
065:
066: /** The return descriptor (return). */
067: public static final short RETURN = 2;
068:
069: /** The author descriptor. */
070: public static final short AUTHOR = 3;
071:
072: /** The version descriptor (version). */
073: public static final short VERSION = 4;
074:
075: /** The reference descriptor (see). */
076: public static final short REFERENCE = 5;
077:
078: //--------------------------------------------------------------------------
079:
080: /** A description string for the object being described. */
081: private String _description = null;
082:
083: /** The name of this JDocDescriptor. */
084: private String _name = null;
085:
086: /** The type of JDocDescriptor, one of {@link #PARAM}, {@link #EXCEPTION},
087: * {@link #RETURN}, {@link #AUTHOR}, {@link #VERSION}, {@link #REFERENCE}. */
088: private short _type = -1;
089:
090: //--------------------------------------------------------------------------
091:
092: /**
093: * Creates a new JDocDescriptor.
094: *
095: * @param type The type of JDocDescriptor (e.g., {@link #REFERENCE}.
096: */
097: private JDocDescriptor(final short type) {
098: _type = type;
099: }
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,
109: final String desc) {
110: _type = type;
111: _name = name;
112: _description = desc;
113: }
114:
115: //--------------------------------------------------------------------------
116:
117: /**
118: * Compares the type of this JDocDescriptor with the given descriptor.
119: * Enables sorting of descriptors.
120: *
121: * @param jdd A JDocDescriptor to be compared to this one.
122: * @return 0 if the two descriptor types are equal, 1 if the type of this
123: * descriptor is greater than the given descriptor, or -1 if the
124: * type of this descriptor is less than the given descriptor.
125: */
126: protected short compareTo(final JDocDescriptor jdd) {
127: short jddType = jdd.getType();
128:
129: if (jddType == this ._type) {
130: return 0;
131: }
132:
133: // The ordering is as follows
134: // #param
135: // #exception
136: // #author
137: // #version
138: // #see (reference)
139: //
140: return (short) ((jddType < this ._type) ? 1 : -1);
141: }
142:
143: /**
144: * Creates a new, empty @author JavaDoc descriptor.
145: *
146: * @return The new JDocDescriptor.
147: */
148: public static JDocDescriptor createAuthorDesc() {
149: return new JDocDescriptor(AUTHOR);
150: }
151:
152: /**
153: * Creates a new @author JavaDoc descriptor with the provided author name
154: * string.
155: *
156: * @param name The author name string.
157: * @return The new JDocDescriptor.
158: */
159: public static JDocDescriptor createAuthorDesc(final String name) {
160: return new JDocDescriptor(AUTHOR, name, null);
161: }
162:
163: /**
164: * Creates a new, empty @exception JavaDoc descriptor.
165: *
166: * @return The new JDocDescriptor.
167: */
168: public static JDocDescriptor createExceptionDesc() {
169: return new JDocDescriptor(EXCEPTION);
170: }
171:
172: /**
173: * Creates a new @exception JavaDoc descriptor with a given exception
174: * name and a description of when the exception is thrown.
175: *
176: * @param name The exception name.
177: * @param desc The description of when the exception is thrown.
178: * @return The new JDocDescriptor.
179: */
180: public static JDocDescriptor createExceptionDesc(final String name,
181: final String desc) {
182: return new JDocDescriptor(EXCEPTION, name, desc);
183: }
184:
185: /**
186: * Creates a new, empty @param JavaDoc descriptor.
187: *
188: * @return The new JDocDescriptor.
189: */
190: public static JDocDescriptor createParamDesc() {
191: return new JDocDescriptor(PARAM);
192: }
193:
194: /**
195: * Creates a new @param JavaDoc descriptor with the given parameter
196: * name and description.
197: *
198: * @param name The param name.
199: * @param desc The param description string.
200: * @return The new JDocDescriptor.
201: */
202: public static JDocDescriptor createParamDesc(final String name,
203: final String desc) {
204: return new JDocDescriptor(PARAM, name, desc);
205: }
206:
207: /**
208: * Creates a new, empty @reference JavaDoc descriptor.
209: *
210: * @return The new JDocDescriptor.
211: */
212: public static JDocDescriptor createReferenceDesc() {
213: return new JDocDescriptor(REFERENCE);
214: }
215:
216: /**
217: * Creates a new @reference JavaDoc descriptor with the provided
218: * reference string.
219: *
220: * @param name The reference name string.
221: * @return The new JDocDescriptor.
222: */
223: public static JDocDescriptor createReferenceDesc(final String name) {
224: return new JDocDescriptor(REFERENCE, name, null);
225: }
226:
227: /**
228: * Creates a new, empty @return JavaDoc descriptor.
229: *
230: * @return The new JDocDescriptor.
231: */
232: public static JDocDescriptor createReturnDesc() {
233: return new JDocDescriptor(RETURN);
234: }
235:
236: /**
237: * Creates a new @return JavaDoc descriptor with the provided
238: * description of what is returned.
239: *
240: * @param desc The return description.
241: * @return The new JDocDescriptor.
242: */
243: public static JDocDescriptor createReturnDesc(final String desc) {
244: return new JDocDescriptor(RETURN, null, desc);
245: }
246:
247: /**
248: * Creates a new, empty @version JavaDoc descriptor.
249: *
250: * @return The new JDocDescriptor.
251: */
252: public static JDocDescriptor createVersionDesc() {
253: return new JDocDescriptor(VERSION);
254: }
255:
256: /**
257: * Creates a new @version JavaDoc descriptor with the provided version
258: * string.
259: *
260: * @param version The version string.
261: * @return The new JDocDescriptor.
262: */
263: public static JDocDescriptor createVersionDesc(final String version) {
264: return new JDocDescriptor(VERSION, null, version);
265: }
266:
267: /**
268: * Returns the description String.
269: *
270: * @return The description string.
271: */
272: public String getDescription() {
273: return _description;
274: }
275:
276: /**
277: * Returns the name of the object being described. This is valid for the
278: * following fields:
279: * <ul>
280: * <li>author</li>
281: * <li>exception</li>
282: * <li>param</li>
283: * <li>see</li>
284: * </ul>
285: *
286: * @return The name of the object being described.
287: */
288: public String getName() {
289: return _name;
290: }
291:
292: /**
293: * Returns the type of this JDocDescriptor.
294: *
295: * @return The type of this JDocDescriptor.
296: */
297: public short getType() {
298: return _type;
299: }
300:
301: /**
302: * Sets the description String for this descriptor.
303: *
304: * @param desc The description of the object being described.
305: */
306: public void setDescription(final String desc) {
307: _description = desc;
308: }
309:
310: /**
311: * Sets the name value of the JavaDoc field. This is only valid for the
312: * following fields:
313: * <ul>
314: * <li>author</li>
315: * <li>exception</li>
316: * <li>param</li>
317: * <li>see</li>
318: * </ul>
319: *
320: * @param name The name value of the JavaDoc field.
321: */
322: public void setName(final String name) {
323: _name = name;
324: }
325:
326: //--------------------------------------------------------------------------
327:
328: /**
329: * {@inheritDoc}
330: */
331: public String toString() {
332: StringBuffer sb = new StringBuffer();
333: boolean allowName = true;
334: switch (_type) {
335: case AUTHOR:
336: sb.append("@author");
337: break;
338: case EXCEPTION:
339: sb.append("@throws");
340: break;
341: case PARAM:
342: sb.append("@param");
343: break;
344: case REFERENCE:
345: sb.append("@see");
346: break;
347: case RETURN:
348: sb.append("@return");
349: break;
350: case VERSION:
351: allowName = false;
352: sb.append("@version");
353: break;
354: default:
355: break;
356: }
357:
358: if ((_name != null) && allowName) {
359: sb.append(' ');
360: sb.append(_name);
361: }
362:
363: if (_description != null) {
364: sb.append(' ');
365: sb.append(_description);
366: }
367:
368: return sb.toString();
369: }
370:
371: //--------------------------------------------------------------------------
372: }
|