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