View Javadoc

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