Java > Open Source Codes > org > openide > src > JavaDocTagMemoryImpl


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 //package org.openide.src;
21 package org.openide.src;
22
23 import org.openide.ErrorManager;
24 import org.openide.src.JavaDocTag;
25
26
27 /**
28  * Represents a documentation tag, e.g. @since, @author, @version.
29  * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")
30  * and tag text (e.g. "1.2"). Tags with structure or which require
31  * special processing are handled by special interfaces (JavaDocTag.See,
32  * JavaDocTag.Param, JavaDocTag.Throws and JavaDocTag.SerialField).
33  * The interfaces provide subset of methods defined in Tag interfaces
34  * in the Doclet API. The implementation holds informations about tags in
35  * memory.
36  *
37  * @author Petr Hrebejk
38  * @see JavaDoc#getTags()
39  *
40  */
41
42 class JavaDocTagMemoryImpl implements JavaDocTag {
43
44     String name;
45     String text;
46
47     JavaDocTagMemoryImpl( String name, String text ) {
48         this.name = name;
49         this.text = JavaDocMemoryImpl.convertNewLines(text);
50     }
51
52     public String toString() {
53         return name + " " + text; // NOI18N
54 }
55
56
57     /**
58      * Return the name of this tag.
59      */
60     public String name() {
61         return name;
62     }
63
64     /**
65      * Return the kind of this tag.
66      */
67     public String kind() {
68         return name;
69     }
70
71     /**
72      * Return the text of this tag, that is, portion beyond tag name.
73      */
74     public String text() {
75         return text;
76     }
77
78     // TAG private & utility methods ------------------------------------------------------
79
80     /**
81      * for use by subclasses which have two part tag text.
82      */
83     String [] divideAtWhite() {
84         String [] sa = new String [2];
85         int len = text.length();
86         // if no white space found
87 sa[0] = text;
88         sa[1] = ""; // NOI18N
89 for (int inx = 0; inx < len; ++inx) {
90             char ch = text.charAt(inx);
91             if (Character.isWhitespace(ch)) {
92                 sa[0] = text.substring(0, inx);
93                 for (; inx < len; ++inx) {
94                     ch = text.charAt(inx);
95                     if (!Character.isWhitespace(ch)) {
96                         sa[1] = text.substring(inx, len);
97                         break;
98                     }
99                 }
100                 break;
101             }
102         }
103         return sa;
104     }
105
106
107     // INNER CLASSES ----------------------------------------------------------------------
108
109     /**
110      * Represents a see also documentation tag.
111      *
112      */
113
114     static class See extends JavaDocTagMemoryImpl implements JavaDocTag.See {
115
116         private String label = ""; // NOI18N
117
118         /** where#what */
119         private String where;
120         private String what;
121
122         See( String name, String text ) {
123             super( name, text );
124             parseSeeString();
125         }
126
127         /**
128          * Return the label of the see tag.
129          */
130         public String label() {
131             return label;
132         }
133
134         /**
135          * get the class name part of @see, For instance,
136          * if the comment is @see String#startsWith(java.lang.String) .
137          * This function returns String.
138          * Returns null if format was not that of java reference.
139          * Return empty string if class name was not specified..
140          */
141         public String referencedClassName() {
142             return where;
143         }
144
145         /**
146          * get the name of the member referenced by the prototype part of @see,
147          * For instance,
148          * if the comment is @see String#startsWith(java.lang.String) .
149          * This function returns "startsWith(java.lang.String)"
150          * Returns null if format was not that of java reference.
151          * Return empty string if member name was not specified..
152          */
153         public String referencedMemberName() {
154             return what;
155         }
156
157         /**
158          * Return the kind of this tag.
159          */
160         public String kind() {
161             return "@see"; // NOI18N
162 }
163
164         /**
165          * Return the rawText for this tag
166          */
167
168         public String toString() {
169             StringBuffer sb = new StringBuffer ( 100 );
170             
171             sb.append( name ).append( " " ).append( text ); // NOI18N
172 return sb.toString();
173         }
174
175         // SEE TAG private & utility methods --------------------------------------------------
176
177         /**
178          * parse @see part of comment. Determine 'where' and 'what'
179          */
180         private void parseSeeString( ) {
181             int len = text.length();
182
183             if (len == 0) {
184                 return;
185             }
186
187             switch (text.charAt(0)) {
188             case '<':
189             case '"':
190                 return;
191             }
192
193             // check that the text is one word, with possible parentheses
194 // this part of code doesn't allow
195 // @see <a HREF=.....>asfd</a>
196 // comment it.
197
198             // the code assumes that there is no initial white space.
199 int parens = 0;
200             int commentstart = 0;
201             int start = 0;
202
203             for (int i = start; i < len ; i++) {
204                 char ch = text.charAt(i);
205                 switch (ch) {
206                 case '(':
207                     parens++;
208                     break;
209                 case ')':
210                     parens--;
211                     break;
212     case '[': case ']': case '.': case '#':
213                     break;
214                 case ',':
215                     if (parens <= 0) {
216                         return;
217                     }
218                     break;
219         case ' ': case '\t': case '\n':
220                     if (parens == 0) { //here onwards the comment starts.
221 commentstart = i;
222                         i = len;
223                     }
224                     break;
225                 default:
226                     if (!Character.isJavaIdentifierPart(ch)) {
227                         return;
228                     }
229                     break;
230                 }
231             }
232             if (parens != 0) {
233                 return;
234             }
235
236             String seetext = ""; // NOI18N
237 String labeltext = ""; // NOI18N
238
239             if (commentstart > 0) {
240                 seetext = text.substring(start, commentstart);
241                 labeltext = text.substring(commentstart + 1);
242                 // strip off the white space which can be between seetext and the
243 // actual label.
244 for (int i = 0; i < labeltext.length(); i++) {
245                     char ch = labeltext.charAt(i);
246                     if (!(ch == ' ' || ch == '\t' || ch == '\n')) {
247                         label = labeltext.substring(i);
248                         break;
249                     }
250                 }
251             }
252             else {
253                 seetext = text;
254                 label = ""; // NOI18N
255 }
256
257             int sharp = seetext.indexOf('#');
258             if (sharp >= 0) {
259                 // class#member
260 where = seetext.substring(0, sharp);
261                 what = seetext.substring(sharp + 1);
262             }
263             else {
264                 if (seetext.indexOf('(') >= 0) {
265                     where = ""; // NOI18N
266 what = seetext;
267                 }
268                 else {
269                     // no member specified, text names class
270 where = seetext;
271                     what = null;
272                 }
273             }
274         }
275     }
276
277     /**
278      * Represents an @param documentation tag.
279      * The parses and stores the name and comment parts of the
280      * method/constructor parameter tag.
281      */
282
283     static class Param extends JavaDocTagMemoryImpl implements JavaDocTag.Param {
284
285         private String parameterName;
286         private String parameterComment;
287
288         Param( String name, String text ) {
289             super( name, text );
290
291             String [] sa = this.divideAtWhite();
292
293             this.parameterName = sa[0];
294             this.parameterComment = sa[1];
295
296             /*
297             if (!(holder instanceof ExecutableMemberDocImpl)) {
298               Warning("tag.not_on_method", " " this.text ); // NOI18N
299         }
300             */
301         }
302
303         /**
304          * Return the parameter name.
305          */
306         public String parameterName() {
307             return parameterName;
308         }
309
310         /**
311          * Return the parameter comment.
312          */
313         public String parameterComment() {
314             return parameterComment;
315         }
316
317         /**
318          * Return the kind of this tag.
319          */
320         public String kind() {
321             return "@param"; // NOI18N
322 }
323
324
325         /**
326          * Return the rawText for this tag
327          */
328         public String toString() {
329             return name + " " + parameterName() + " " + parameterComment(); // NOI18N
330 }
331     }
332
333     /**
334      * Represents a @throws or @exception documentation tag.
335      * Parses and holds the exception name and exception comment.
336      * Note: @exception is a backwards compatible synonymy for @throws.
337      */
338     static class Throws extends JavaDocTagMemoryImpl implements JavaDocTag.Throws {
339
340         private String exceptionName;
341         private String exceptionComment;
342
343         Throws( String name, String text ) {
344             super( name, text );
345
346             /*
347             if (runtimeException == null) {
348               runtimeException = ClassDocImpl.lookup("java.lang.RuntimeException"); // NOI18N
349         }
350             */
351             String [] sa = this.divideAtWhite();
352             this.exceptionName = sa[0];
353             this.exceptionComment = sa[1];
354
355             /*
356             if (!(holder instanceof ExecutableMemberDocImpl)) {
357               Res.warning("tag.not_on_method", holder.toString(), this.text); // NOI18N
358               exceptionClass = null;
359         }
360             else {
361               ExecutableMemberDocImpl emd = (ExecutableMemberDocImpl)holder;
362               ClassDoc con = emd.containingClass();
363               exceptionClass = con.findClass(exceptionName);
364               if (exceptionClass == null) {
365                   // may just not be in this run
366                   // Res.warning("tag.throws.exception_not_found", // NOI18N
367                   // emd.qualifiedName(), kind(), exceptionName);
368               }
369               else {
370                 if (!isOK(exceptionClass, emd.thrownExceptions())) {
371                     Res.warning("tag.throws.does_not_declare", emd.qualifiedName(), exceptionClass.qualifiedName()); // NOI18N
372                 }
373               }
374         }
375             */
376         }
377
378         /**
379          * Return the exception name.
380          */
381         public String exceptionName() {
382             return exceptionName;
383         }
384
385         /**
386          * Return the exception comment.
387          */
388         public String exceptionComment() {
389             return exceptionComment;
390         }
391
392         /**
393          * Return the kind of this tag. Always "@throws" for instances
394          * of ThrowsTagImpl.
395          */
396         public String kind() {
397             return "@throws"; // NOI18N
398 }
399
400         /**
401          * Return the rawText for this tag
402          */
403         public String toString() {
404             return name + " " + exceptionName() + " " + exceptionComment(); // NOI18N
405 }
406     }
407
408     /**
409      * Documents a Serializable field defined by an ObjectStreamField.
410      * <pre>
411      * The class parses and stores the three serialField tag parameters:
412      *
413      * - field name
414      * - field type name
415      * (fully-qualified or visible from the current import context)
416      * - description of the valid values for the field
417
418      * </pre>
419      * This tag is only allowed in the javadoc for the special member
420      *
421      * @see java.io.ObjectStreamField
422      */
423
424     static class SerialField extends JavaDocTagMemoryImpl implements JavaDocTag.SerialField {
425
426         private String fieldName;
427         private String fieldType;
428         private String description;
429
430
431         SerialField( String name, String text ) {
432             super( name, text );
433             parseSerialFieldString( text );
434         }
435
436
437         /**
438          * Return the serialziable field name.
439          */
440         public String fieldName() {
441             return fieldName;
442         }
443
444         /**
445          * Return the field type string.
446          */
447         public String fieldType() {
448             return fieldType;
449         }
450
451         /**
452          * Return the field comment. If there is no serialField comment, return
453          * javadoc comment of corresponding FieldDoc.
454          */
455         public String description() {
456             return description;
457         }
458
459         /**
460          * Return the kind of this tag.
461          */
462         public String kind() {
463             return "@serialField"; // NOI18N
464 }
465
466         /**
467          * Return the rawText for this tag
468          */
469
470         public String toString() {
471             return name + " " + fieldName() + " " + fieldType() + " " + description(); // NOI18N
472 }
473
474         /*
475         * The serialField tag is composed of three entities.
476         *
477         * serialField serializableFieldName serisliableFieldType
478         * description of field.
479         *
480         * The fieldName and fieldType must be legal Java Identifiers.
481         */
482         private void parseSerialFieldString( String text) {
483
484             int len = text.length();
485
486             // if no white space found
487 // Skip white space.
488 int inx = 0;
489             for (; inx < len && Character.isWhitespace(text.charAt(inx)); inx++) ;
490
491             if ( inx == len ) {
492                 fieldName = ""; // NOI18N
493 fieldType = ""; // NOI18N
494 description = ""; // NOI18N
495 return;
496             }
497
498             // Find first word.
499 int first = inx;
500             int last = inx;
501             if (! Character.isJavaIdentifierStart(text.charAt(inx))) {
502                 return;
503             }
504
505             for (; inx < len && Character.isJavaIdentifierPart(text.charAt(inx)); inx++);
506
507             if (inx < len && ! Character.isWhitespace(text.charAt(inx))) {
508                 return;
509             }
510
511             last = inx;
512             fieldName = text.substring(first, last);
513
514             // Skip white space.
515 for (; inx < len && Character.isWhitespace(text.charAt(inx)); inx++) ;
516
517             // Find second word.
518 first = inx;
519             last = inx;
520
521             for (; inx < len && ! Character.isWhitespace(text.charAt(inx)); inx++);
522             if (inx < len && ! Character.isWhitespace(text.charAt(inx))) {
523                 return;
524             }
525             last = inx;
526             fieldType = text.substring(first, last);
527
528             // Skip leading white space. Rest of string is description for serialField.
529 for (; inx < len && Character.isWhitespace(text.charAt(inx)); inx++) ;
530             description = text.substring(inx);
531         }
532
533     }
534
535 }
536

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags