KickJava   Java API By Example, From Geeks To Geeks.

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


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
22 /**
23  * Represents a documentation tag, e.g. @since, @author, @version.
24  * Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since")
25  * and tag text (e.g. "1.2"). Tags with structure or which require
26  * special processing are handled by special interfaces (JavaDocTag.See,
27  * JavaDocTag.Param, JavaDocTag.Throws and JavaDocTag.SerialField).
28  * The interfaces provide subset of methods defined in Tag interfaces
29  * in the Doclet API.
30  *
31  * @author Petr Hrebejk
32  * @see JavaDoc#getTags()
33  *
34  */
35
36 public interface JavaDocTag {
37
38     /**
39      * Return the name of this tag.
40      */
41     String JavaDoc name();
42
43     /**
44      * Return the kind of this tag.
45      */
46     String JavaDoc kind();
47
48     /**
49      * Return the text of this tag, that is, portion beyond tag name.
50      */
51     String JavaDoc text();
52
53     /**
54      * Represents a see also documentation tag.
55      *
56      */
57
58     public static interface See extends JavaDocTag {
59
60         /**
61          * Return the label of the see tag.
62          */
63         String JavaDoc label();
64
65         /**
66          * get the class name part of @see, For instance,
67          * if the comment is @see String#startsWith(java.lang.String) .
68          * This function returns String.
69          * Returns null if format was not that of java reference.
70          * Return empty string if class name was not specified..
71          */
72         String JavaDoc referencedClassName();
73
74         /**
75          * get the name of the member referenced by the prototype part of @see,
76          * For instance,
77          * if the comment is @see String#startsWith(java.lang.String) .
78          * This function returns "startsWith(java.lang.String)"
79          * Returns null if format was not that of java reference.
80          * Return empty string if member name was not specified..
81          */
82         String JavaDoc referencedMemberName();
83
84     }
85
86     /**
87      * Represents an @param documentation tag.
88      * The parses and stores the name and comment parts of the
89      * method/constructor parameter tag.
90      */
91
92     public static interface Param extends JavaDocTag {
93
94         /**
95          * Return the parameter name.
96          */
97         String JavaDoc parameterName();
98
99         /**
100          * Return the parameter comment.
101          */
102         String JavaDoc parameterComment();
103     }
104
105     /**
106      * Represents a @throws or @exception documentation tag.
107      * Parses and holds the exception name and exception comment.
108      * Note: @exception is a backwards compatible synonymy for @throws.
109      */
110     public static interface Throws extends JavaDocTag {
111
112         /**
113         * Return the exception name.
114         */
115         String JavaDoc exceptionName();
116
117         /**
118          * Return the exception comment.
119          */
120         String JavaDoc exceptionComment();
121
122     }
123
124     /**
125      * Documents a Serializable field defined by an ObjectStreamField.
126      * <pre>
127      * The class parses and stores the three serialField tag parameters:
128      *
129      * - field name
130      * - field type name
131      * (fully-qualified or visible from the current import context)
132      * - description of the valid values for the field
133
134      * </pre>
135      * This tag is only allowed in the javadoc for the special member
136      *
137      * @see java.io.ObjectStreamField
138      */
139
140     public static interface SerialField extends JavaDocTag {
141         /**
142          * Return the serialziable field name.
143          */
144         public String JavaDoc fieldName();
145
146         /**
147          * Return the field type string.
148          */
149         public String JavaDoc fieldType();
150
151         /**
152          * Return the field comment. If there is no serialField comment, return
153          * javadoc comment of corresponding FieldDoc.
154          */
155         public String JavaDoc description();
156     }
157
158 }
159
Popular Tags