Source code: com/halesoft/jcomment/JavaDocTag.java
1 /*******************************************************************************
2 ** JComment - Javadoc comment generator **
3 ** Copyright (C) 2000. J. Benjamin Hale **
4 ** nebhale@hotmail.com - http://nebhale.tripod.com **
5 ** **
6 ** This program is free software; you can redistribute it and/or **
7 ** modify it under the terms of the GNU General Public License **
8 ** as published by the Free Software Foundation; either version 2 **
9 ** of the License, or (at your option) any later version. **
10 ** **
11 ** This program is distributed in the hope that it will be useful, **
12 ** but WITHOUT ANY WARRANTY; without even the implied warranty of **
13 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the **
14 ** GNU General Public License for more details. **
15 ** **
16 ** You should have received a copy of the GNU General Public License **
17 ** along with this program; if not, write to the Free Software **
18 ** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.**
19 *******************************************************************************/
20 package com.halesoft.jcomment;
21
22
23
24
25
26 /**
27 * Represents a documentation tag such as:
28 * <pre>
29 * author
30 * deprecated
31 * exception
32 * param
33 * return
34 * see
35 * serial
36 * serialData
37 * serialField
38 * since
39 * throws
40 * version
41 * </pre>
42 *
43 * <p>Given a tag, holds tag and tag text. Tags with structure or which
44 * require special processing are handled by special interfaces (JavaDocTag.See,
45 * JavaDocTag.Param, JavaDocTag.Throws, and JavaDocTag.SerialField).
46 *
47 * <p>The interfaces provide subset of methods defined in Tag interfaces in the
48 * Doclet API.
49 *
50 * <p>This implementation holds informations about tags in memory.
51 *
52 * @author J. Benjamin Hale
53 * @version 1.0
54 */
55 public final class JavaDocTag
56 {
57 /** Tag name storage. */
58 private String name_ = new String();
59 /** Tag type storage */
60 private String text_ = new String();
61
62
63
64
65
66 /**
67 * Creates a <code>JavaDocTag</code> object with a name and text beyond
68 * the tag name.
69 *
70 * @param name Tag name.
71 * @param text Tag text.
72 */
73 public JavaDocTag (String name, String text) {
74 name_ = name;
75 text_ = text;
76 }
77
78
79
80
81
82 /**
83 * Returns a fully formed tag.
84 *
85 * @return Fully formed tag.
86 */
87 public String toString () {
88 return name_ + " " + text_;
89 }
90
91
92
93
94
95 /**
96 * Returns the name of this tag.
97 *
98 * @return Name of this tag.
99 */
100 public String getName () {
101 return name_;
102 }
103
104
105
106
107
108 /**
109 * Returns the kind of this tag.
110 *
111 * @return Kind of this tag.
112 */
113 public String getKind () {
114 return name_;
115 }
116
117
118
119
120
121 /**
122 * Returns the text of this tag.
123 *
124 * @return Text of this tag.
125 */
126 public String getText () {
127 return text_;
128 }
129
130
131
132
133
134 /**
135 * Partitions tags that have two parts of tag text. Used by subclasses
136 * of this class.
137 *
138 * @return Array with parsed pieces of the tag text.
139 */
140 protected String[] divideAtWhite () {
141 String[] sa = new String[2];
142 int len = text_.length();
143
144 sa[0] = text_;
145 sa[1] = "";
146
147 for (int i = 0; i < len; ++i) {
148
149 char c = text_.charAt (i);
150 if (Character.isWhiteSpace (c)) {
151 sa[0] = text_.substring (0, i);
152
153 for (; i < len; ++i) {
154
155 c = text_.charAt (i);
156 if (!Character.isWhiteSpace (c)) {
157 sa[1] = text_.substring (i, len);
158 break;
159 }
160 }
161 break;
162 }
163 }
164
165 return sa;
166 }
167
168
169
170
171
172 /**
173 * Prints warning message to the console.
174 *
175 * @param s1 Error type.
176 * @param s2 Invalid text.
177 */
178 protected void printWarning (String s1, String s2) {
179 System.out.println ("WARNING: " + s1 + s2);
180 }
181
182
183
184
185
186 /**
187 * Represents a <code>see</code> documentation tag.
188 */
189 public static class See extends JavaDocTag
190 {
191 /** See tag label storage. */
192 private String label_ = new String();
193 /** Class name part of see tag. */
194 private String className_ = new String();
195 /** Member referenced by the prototype part of the see tag. */
196 private String memberName_ = new String();
197
198
199
200
201
202 /**
203 * Creates a <code>JavaDocTag.See</code> object with a name and text
204 * beyond the tag name.
205 *
206 * @param name Tag name.
207 * @param text Tag text.
208 */
209 public See (String name, String text) {
210 super (name, text);
211 parseSeeString();
212 }
213
214
215
216
217
218 /**
219 * Returns a fully formed tag.
220 *
221 * @return Fully formed tag.
222 */
223 public String toString () {
224 StringBuffer sb = new StringBuffer ();
225
226 sb.append (name).append (" ");
227
228 if (getReferencedClassName() != null)
229 sb.append (getReferencedClassName());
230
231 sb.append ("#");
232
233 if (getReferencedMemberName() != null)
234 sb.append (getReferencedClassName());
235
236 sb.append (" ");
237
238 if (label != null)
239 sb.append (label);
240
241 return sb.toString();
242 }
243
244
245
246
247
248 /**
249 * Returns the label of the see tag.
250 *
251 * @return Label of the see tag.
252 */
253 public String getLabel () {
254 return label_;
255 }
256
257
258
259
260
261 /**
262 * Returns the kind of this tag.
263 *
264 * @return Kind of this tag.
265 */
266 public String getKind () {
267 return new String ("@see");
268 }
269
270
271
272
273
274 /**
275 * Returns the class name part of <code>see</code>.
276 *
277 * <p>For instance, if the comment is
278 * <code>see String#startsWith (java.lang.String)</code>, this funtion
279 * returns "String".
280 *
281 * <p>Returns null if format was not that of java reference.
282 * <p>Returns empty string if class name was not specified.
283 * @return Class name part of <CODE>see</CODE>.
284 */
285 public String getReferencedClassName () {
286 return className_;
287 }
288
289
290
291
292
293 /**
294 * Returns the name of the member referenced by the prototype part of
295 * <code>see</code>.
296 *
297 * <p>For instance, if the comment is
298 * <code>see String#startsWith (java.lang.String)</code>, this funtion
299 * returns "startsWith (java.lang.String)"
300 *
301 * <p>Returns null if format was not that of java reference.
302 * <p>Returns empty string if member name was not specified.
303 * @return Member referenced by the prototype part of <CODE>see</CODE>.
304 */
305 public String getReferencedMemberName () {
306 return memberName_;
307 }
308
309
310
311
312
313 /**
314 * Parses see tag to determine <code>className_</code>, and
315 * <code>memberName_</code>.
316 */
317 private void parseSeeString () {
318 }
319 }
320
321
322
323
324
325 /**
326 * Represents a <code>param</code> documentation tag.
327 *
328 * <p>Parses and holds the name and comment parts of the method/constructor
329 * parameter tag.
330 */
331 public static class Param extends JavaDocTag
332 {
333 /** Parameter name. */
334 private String parameterName_ = new String();
335 /** Parameter comment. */
336 private String parameterComment_ = new String();
337
338
339
340
341
342 /**
343 * Creates a <code>JavaDocTag.Param</code> object with a name and text
344 * beyond the tag name.
345 *
346 * @param name Tag name.
347 * @param text Tag text.
348 */
349 public Param (String name, String text) {
350 super (name, text);
351
352 String[] sa = divideAtWhite();
353
354 parameterName_ = sa[0];
355 parameterComment = sa[1];
356 }
357
358
359
360
361
362 /**
363 * Returns a fully formed tag.
364 *
365 * @return Fully formed tag.
366 */
367 public String toString () {
368 return name + " " + getParameterName() + " " + getParameterComment();
369 }
370
371
372
373
374
375 /**
376 * Returns the kind of this tag.
377 *
378 * @return Kind of this tag.
379 */
380 public String getKind () {
381 return "@param";
382 }
383
384
385
386
387
388 /**
389 * Returns the parameter name.
390 *
391 * @return Parameter name.
392 */
393 public String getParameterName () {
394 return parameterName_;
395 }
396
397
398
399
400
401 /**
402 * Returns the parameter comment.
403 *
404 * @return Parameter comment.
405 */
406 public String getParameterComment () {
407 return parameterComment();
408 }
409 }
410
411
412
413
414
415 /**
416 * Represents a <code>throws</code> or an <code>exception</code>
417 * documentation tag.
418 *
419 * <p>Parses and holds the exception name and exception comment.
420 *
421 * <p><b>NOTE:</b> <code>exception</code is a backwards compatible
422 * synonym for </code>throws</code>.
423 */
424 public static class Throws extends JavaDocTag
425 {
426 /** Exception name. */
427 private String exceptionName_ = new String();
428 /** Exception comment. */
429 private String exceptionComment_ = new String();
430
431
432
433
434
435 /**
436 * Creates a <code>JavaDocTag.Throws</code> object with a name and text
437 * beyond the tag name.
438 *
439 * @param name Tag name.
440 * @param text Tag text.
441 */
442 public Throws (String name, String text) {
443 super (name, text);
444
445 String[] sa = divideAtWhite();
446
447 exceptionName_ = sa[0];
448 exceptionComment_ = sa[1];
449 }
450
451
452
453
454
455 /**
456 * Returns a fully formed tag.
457 *
458 * @return Fully formed tag.
459 */
460 public String toString () {
461 return name + " " + getExceptionName() + " " +
462 getExceptionComment();
463 }
464
465
466
467
468
469 /**
470 * Returns the kind of this tag.
471 *
472 * @return Kind of this tag.
473 */
474 public String getKind () {
475 return new String ("@throws");
476 }
477
478
479
480
481
482 /**
483 * Returns the exception name.
484 *
485 * @return Exception name.
486 */
487 public String getExceptionName () {
488 return exceptionName_;
489 }
490
491
492
493
494
495 /**
496 * Returns the exception comment.
497 *
498 * @return Exception comment.
499 */
500 public String getExceptionComment () {
501 return exceptionComment_;
502 }
503 }
504
505
506
507
508
509
510 /**
511 * Represents an <code>serialField</code> documentation tag defined by an
512 * ObjectStreamField.
513 *
514 * <p>The class parases and stores the three serialField tag paramaters:
515 * <pre>
516 * - field name
517 * - field type name
518 * (fully-qualified or visible from the current import context)
519 * - description of the valid values for the field
520 * </pre>
521 *
522 * <p>This tag is only allowed in the javadoc for special special members.
523 *
524 * @see java.io.ObjectStreamField
525 */
526 public static class SerialField extends JavaDocTag
527 {
528 /**
529 * Returns the serializable field name.
530 *
531 * @return Serializable field name.
532 */
533 public String fieldName ();
534
535
536
537
538
539 /**
540 * Returns the serializable field type.
541 *
542 * @return Serializeable field type.
543 */
544 public String fieldType ();
545
546
547
548
549
550 /**
551 * Returns the field comment.
552 *
553 * <p>If there is no serialField comment, return javadoc comment of
554 * corresponding FieldDoc.
555 *
556 * @return Field comment.
557 */
558 public String description ();
559 }
560 }