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      * @return 0 if the two descriptor types are equal, 1 if the type of
151      * this descriptor is greater than the given descriptor, or -1 if the
152      * type of this descriptor is less than the given descriptor
153      **/
154     protected short compareTo( JDocDescriptor jdd )
155     {
156         short jddType = jdd.getType();
157 
158         if ( jddType == this.type ) return 0;
159 
160         // The ordering is as follows
161         // #param
162         // #exception
163         // #author
164         // #version
165         // #see (reference)
166         //
167         return (short) ( ( jddType < this.type ) ? 1 : -1 );
168 
169     } //-- compareTo
170 
171     /**
172      * Creates a new author descriptor
173      * @return the new JDocDescriptor
174      **/
175     public static JDocDescriptor createAuthorDesc()
176     {
177         return new JDocDescriptor( AUTHOR );
178     } //-- createAuthorDesc
179 
180     /**
181      * Creates a new author descriptor
182      * @param name the author name string
183      * @return the new JDocDescriptor
184      **/
185     public static JDocDescriptor createAuthorDesc( String name )
186     {
187         return new JDocDescriptor( AUTHOR, name, null );
188     } //-- createAuthorDesc
189 
190     /**
191      * Creates a new exception descriptor
192      * @return the new JDocDescriptor
193      **/
194     public static JDocDescriptor createExceptionDesc()
195     {
196         return new JDocDescriptor( EXCEPTION );
197     } //-- createExceptionDesc
198 
199     /**
200      * Creates a new exception descriptor
201      * @param name the exception name
202      * @param desc the description of when the exception is called
203      * @return the new JDocDescriptor
204      **/
205     public static JDocDescriptor createExceptionDesc
206         ( String name, String desc )
207     {
208         return new JDocDescriptor( EXCEPTION, name, desc );
209     } //-- createExceptionDesc
210 
211 
212     /**
213      * Creates a new param descriptor
214      * @return the new JDocDescriptor
215      **/
216     public static JDocDescriptor createParamDesc()
217     {
218         return new JDocDescriptor( PARAM );
219     } //-- createParamDesc
220 
221     /**
222      * Creates a new param descriptor
223      * @param name the param name
224      * @param desc the param description string
225      * @return the new JDocDescriptor
226      **/
227     public static JDocDescriptor createParamDesc( String name, String desc )
228     {
229         return new JDocDescriptor( PARAM, name, desc );
230     } //-- createParamDesc
231 
232 
233     /**
234      * Creates a new reference descriptor
235      * @return the new JDocDescriptor
236      **/
237     public static JDocDescriptor createReferenceDesc()
238     {
239         return new JDocDescriptor( REFERENCE );
240     } //-- createReferenceDesc
241 
242     /**
243      * Creates a new reference descriptor
244      * @param name the reference name string
245      * @return the new JDocDescriptor
246      **/
247     public static JDocDescriptor createReferenceDesc( String name )
248     {
249         return new JDocDescriptor( REFERENCE, name, null );
250     } //-- createReferenceDesc
251 
252     /**
253      * Creates a new return descriptor
254      * @return the new JDocDescriptor
255      **/
256     public static JDocDescriptor createReturnDesc()
257     {
258         return new JDocDescriptor( RETURN );
259     } //-- createReferenceDesc
260 
261     /**
262      * Creates a new return descriptor
263      * @param desc the return description
264      * @return the new JDocDescriptor
265      **/
266     public static JDocDescriptor createReturnDesc( String desc )
267     {
268         return new JDocDescriptor( RETURN, null, desc );
269     } //-- createReturnDesc
270 
271     /**
272      * Creates a new version descriptor
273      * @return the new JDocDescriptor
274      **/
275     public static JDocDescriptor createVersionDesc()
276     {
277         return new JDocDescriptor( VERSION );
278     } //-- createVersionDesc
279 
280     /**
281      * Creates a new version descriptor
282      * @param version the version string
283      * @return the new JDocDescriptor
284      **/
285     public static JDocDescriptor createVersionDesc( String version )
286     {
287         return new JDocDescriptor( VERSION, null, version );
288     } //-- createVersionDesc
289 
290     /**
291      * Returns the description String for this descriptor
292      * @return the description string for this descriptor
293      **/
294     public String getDescription()
295     {
296         return description;
297     } //-- getDescription
298 
299     /**
300      * Returns the name of the object being described. This
301      * is valid for the following fields:<br>
302      *  <ul>
303      *     <li>author</li>
304      *     <li>exception</li>
305      *     <li>param</li>
306      *     <li>see</li>
307      *  </ul>
308      * @return the name of the object being described. This
309      **/
310     public String getName()
311     {
312         return name;
313     } //-- getName
314 
315     /**
316      * Returns the type of this JDocDescriptor
317      * @return the type of this JDocDescriptor
318      **/
319     public short getType()
320     {
321         return this.type;
322     } //-- getType
323 
324     /**
325      * Sets the description String for this descriptor
326      * @param desc the description of the object being described
327      **/
328     public void setDescription( String desc )
329     {
330         this.description = desc;
331     } //-- setDescription
332 
333 
334     /**
335      * Sets the name value of the JavaDoc field. This is
336      * only valid for the following fields:<br>
337      *  <ul>
338      *     <li>author</li>
339      *     <li>exception</li>
340      *     <li>param</li>
341      *     <li>see</li>
342      *  </ul>
343      * @param name the name value of the JavaDoc field
344      **/
345     public void setName( String name )
346     {
347         this.name = name;
348     } //-- setName
349 
350     /**
351      * Returns the String representation of this JDocDescriptor
352      * @return the String representation of this JDocDescriptor
353      **/
354     public String toString()
355     {
356         StringBuffer sb = new StringBuffer();
357         boolean allowName = true;
358         switch ( type )
359         {
360             case AUTHOR:
361                 sb.append( "@author" );
362                 break;
363             case EXCEPTION:
364                 sb.append( "@throws" );
365                 break;
366             case PARAM:
367                 sb.append( "@param" );
368                 break;
369             case REFERENCE:
370                 sb.append( "@see" );
371                 break;
372             case RETURN:
373                 sb.append( "@return" );
374                 break;
375             case VERSION:
376                 allowName = false;
377                 sb.append( "@version" );
378                 break;
379             default:
380                 break;
381         }
382 
383         if ( ( name != null ) && allowName )
384         {
385             sb.append( ' ' );
386             sb.append( name );
387         }
388 
389         if ( description != null )
390         {
391             sb.append( ' ' );
392             sb.append( description );
393         }
394 
395         return sb.toString();
396     } //-- toString
397 
398 } //-- JDocDescriptor