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@codehaus.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.codehaus.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 * $Id$
44 */
45 package org.codehaus.modello.plugin.java.javasource;
46
47 /*
48 * Copyright (c) 2004, Codehaus.org
49 *
50 * Permission is hereby granted, free of charge, to any person obtaining a copy of
51 * this software and associated documentation files (the "Software"), to deal in
52 * the Software without restriction, including without limitation the rights to
53 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
54 * of the Software, and to permit persons to whom the Software is furnished to do
55 * so, subject to the following conditions:
56 *
57 * The above copyright notice and this permission notice shall be included in all
58 * copies or substantial portions of the Software.
59 *
60 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
61 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
62 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
63 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
64 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
65 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
66 * SOFTWARE.
67 */
68
69 /**
70 * A descriptor for a JavaDoc comment
71 * @author <a href="mailto:kvisco@intalio.com">Keith Visco</a>
72 * @version $Revision$ $Date$
73 **/
74 public class JDocDescriptor {
75
76 /**
77 * The default version string
78 **/
79 // -- separated using "+" so that CVS doesn't expand
80 public static final String DEFAULT_VERSION = "$" + "Revision" + "$ $" + "Date" + "$";
81
82 // -- These are listed in order of how they should
83 // -- appear in a JavaDoc list, so the numbers
84 // -- are important...see #compareTo
85 /**
86 * The param descriptor (param)
87 **/
88 public static final short PARAM = 0;
89
90 /**
91 * The exception descriptor (exception)
92 **/
93 public static final short EXCEPTION = 1;
94
95 /**
96 * The return descriptor (return)
97 **/
98 public static final short RETURN = 2;
99
100 /**
101 * The author descriptor
102 **/
103 public static final short AUTHOR = 3;
104
105 /**
106 * the version descriptor (version)
107 **/
108 public static final short VERSION = 4;
109
110 /**
111 * The reference descriptor (see)
112 **/
113 public static final short REFERENCE = 5;
114
115 private String description = null;
116 private String name = null;
117 private short type = -1;
118
119 /**
120 * Creates a new JDocDescriptor
121 **/
122 private JDocDescriptor(short type) {
123 this.type = type;
124 } // -- JDocDescriptor
125
126 /**
127 * Creates a new JDocDescriptor
128 * @param name the name string for this descriptor
129 * @param desc the description string for this descriptor
130 **/
131 private JDocDescriptor(short type, String name, String desc) {
132 this.type = type;
133 this.name = name;
134 this.description = desc;
135 } // -- JDocDescriptor
136
137 /**
138 * Compares the type of this JDocDescriptor with the given descriptor.
139 * Enables sorting of descriptors.
140 * @param jdd the javadoc descriptor
141 * @return 0 if the two descriptor types are equal, 1 if the type of
142 * this descriptor is greater than the given descriptor, or -1 if the
143 * type of this descriptor is less than the given descriptor
144 **/
145 protected short compareTo(JDocDescriptor jdd) {
146 short jddType = jdd.getType();
147
148 if (jddType == this.type) return 0;
149
150 // The ordering is as follows
151 // #param
152 // #exception
153 // #author
154 // #version
155 // #see (reference)
156 //
157 return (short) ((jddType < this.type) ? 1 : -1);
158 } // -- compareTo
159
160 /**
161 * Creates a new author descriptor
162 * @return the new JDocDescriptor
163 **/
164 public static JDocDescriptor createAuthorDesc() {
165 return new JDocDescriptor(AUTHOR);
166 } // -- createAuthorDesc
167
168 /**
169 * Creates a new author descriptor
170 * @param name the author name string
171 * @return the new JDocDescriptor
172 **/
173 public static JDocDescriptor createAuthorDesc(String name) {
174 return new JDocDescriptor(AUTHOR, name, null);
175 } // -- createAuthorDesc
176
177 /**
178 * Creates a new exception descriptor
179 * @return the new JDocDescriptor
180 **/
181 public static JDocDescriptor createExceptionDesc() {
182 return new JDocDescriptor(EXCEPTION);
183 } // -- createExceptionDesc
184
185 /**
186 * Creates a new exception descriptor
187 * @param name the exception name
188 * @param desc the description of when the exception is called
189 * @return the new JDocDescriptor
190 **/
191 public static JDocDescriptor createExceptionDesc(String name, String desc) {
192 return new JDocDescriptor(EXCEPTION, name, desc);
193 } // -- createExceptionDesc
194
195 /**
196 * Creates a new param descriptor
197 * @return the new JDocDescriptor
198 **/
199 public static JDocDescriptor createParamDesc() {
200 return new JDocDescriptor(PARAM);
201 } // -- createParamDesc
202
203 /**
204 * Creates a new param descriptor
205 * @param name the param name
206 * @param desc the param description string
207 * @return the new JDocDescriptor
208 **/
209 public static JDocDescriptor createParamDesc(String name, String desc) {
210 return new JDocDescriptor(PARAM, name, desc);
211 } // -- createParamDesc
212
213 /**
214 * Creates a new reference descriptor
215 * @return the new JDocDescriptor
216 **/
217 public static JDocDescriptor createReferenceDesc() {
218 return new JDocDescriptor(REFERENCE);
219 } // -- createReferenceDesc
220
221 /**
222 * Creates a new reference descriptor
223 * @param name the reference name string
224 * @return the new JDocDescriptor
225 **/
226 public static JDocDescriptor createReferenceDesc(String name) {
227 return new JDocDescriptor(REFERENCE, name, null);
228 } // -- createReferenceDesc
229
230 /**
231 * Creates a new return descriptor
232 * @return the new JDocDescriptor
233 **/
234 public static JDocDescriptor createReturnDesc() {
235 return new JDocDescriptor(RETURN);
236 } // -- createReferenceDesc
237
238 /**
239 * Creates a new return descriptor
240 * @param desc the return description
241 * @return the new JDocDescriptor
242 **/
243 public static JDocDescriptor createReturnDesc(String desc) {
244 return new JDocDescriptor(RETURN, null, desc);
245 } // -- createReturnDesc
246
247 /**
248 * Creates a new version descriptor
249 * @return the new JDocDescriptor
250 **/
251 public static JDocDescriptor createVersionDesc() {
252 return new JDocDescriptor(VERSION);
253 } // -- createVersionDesc
254
255 /**
256 * Creates a new version descriptor
257 * @param version the version string
258 * @return the new JDocDescriptor
259 **/
260 public static JDocDescriptor createVersionDesc(String version) {
261 return new JDocDescriptor(VERSION, null, version);
262 } // -- createVersionDesc
263
264 /**
265 * Returns the description String for this descriptor
266 * @return the description string for this descriptor
267 **/
268 public String getDescription() {
269 return description;
270 } // -- getDescription
271
272 /**
273 * Returns the name of the object being described. This
274 * is valid for the following fields:<br>
275 * <ul>
276 * <li>author</li>
277 * <li>exception</li>
278 * <li>param</li>
279 * <li>see</li>
280 * </ul>
281 * @return the name of the object being described. This
282 **/
283 public String getName() {
284 return name;
285 } // -- getName
286
287 /**
288 * Returns the type of this JDocDescriptor
289 * @return the type of this JDocDescriptor
290 **/
291 public short getType() {
292 return this.type;
293 } // -- getType
294
295 /**
296 * Sets the description String for this descriptor
297 * @param desc the description of the object being described
298 **/
299 public void setDescription(String desc) {
300 this.description = desc;
301 } // -- setDescription
302
303 /**
304 * Sets the name value of the JavaDoc field. This is
305 * only valid for the following fields:<br>
306 * <ul>
307 * <li>author</li>
308 * <li>exception</li>
309 * <li>param</li>
310 * <li>see</li>
311 * </ul>
312 * @param name the name value of the JavaDoc field
313 **/
314 public void setName(String name) {
315 this.name = name;
316 } // -- setName
317
318 /**
319 * Returns the String representation of this JDocDescriptor
320 * @return the String representation of this JDocDescriptor
321 **/
322 public String toString() {
323 StringBuilder sb = new StringBuilder();
324 boolean allowName = true;
325 switch (type) {
326 case AUTHOR:
327 sb.append("@author");
328 break;
329 case EXCEPTION:
330 sb.append("@throws");
331 break;
332 case PARAM:
333 sb.append("@param");
334 break;
335 case REFERENCE:
336 sb.append("@see");
337 break;
338 case RETURN:
339 sb.append("@return");
340 break;
341 case VERSION:
342 allowName = false;
343 sb.append("@version");
344 break;
345 default:
346 break;
347 }
348
349 if ((name != null) && allowName) {
350 sb.append(' ');
351 sb.append(name);
352 }
353
354 if (description != null) {
355 sb.append(' ');
356 sb.append(description);
357 }
358
359 return sb.toString();
360 } // -- toString
361 } // -- JDocDescriptor