KickJava   Java API By Example, From Geeks To Geeks.

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


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 /** Represents a JavaDoc comment block. The representation object is mutable,
23  * if it represents a portion of a source text, any changes made to the object
24  * are reflected in the source code and vice versa.<BR>
25  * There are a few inerclasses, which subclass JavaDoc class, and add accessors for tags specific
26  * to individual source text elements.
27  *
28 * @author Jaroslav Tulach, Petr Hrebejk, Petr Hamernik
29 */
30 public interface JavaDoc {
31
32     /** Serves as second parameter in method {@link #changeTags}.
33      */
34     public static final int ADD = 1;
35
36     /** Serves as second parameter in method {@link #changeTags}.
37      */
38     public static final int REMOVE = 2;
39
40     /** Serves as second parameter in method {@link #changeTags}.
41      */
42     public static final int SET = 3;
43
44     /** Get the entire text of the comment. If the javadoc comment is empty (except the boxing
45      * stars), it returns an empty string. If the comment is missing at all, the method returns <code>null</code>
46      * ({@link #isEmpty} returns <code>true</code> at the same time).
47     * @return the whole text, or <code>null</code>, if the comment is missing at all on the {@link Element}.
48     */
49     public String JavaDoc getRawText ();
50
51     /** Set the raw text of the comment.
52     * @param s the whole text to set
53     * @exception SourceException if the modification cannot be performed
54     */
55     public void setRawText (String JavaDoc s) throws SourceException;
56
57     /** Get the actual text, cleared of all (non-inline) tags.
58     * @return the plain text
59     */
60     public String JavaDoc getText ();
61
62     /** Set the actual text.
63     * @param s the actual text, without any (non-inline) tags
64     * @exception SourceException if the modification cannot be performed
65     */
66     public void setText (String JavaDoc s) throws SourceException;
67
68     /** Clears the javadoc from the source.
69     */
70     public void clearJavaDoc() throws SourceException;
71
72     /** Test if this javadoc is empty.
73     * @return true if it is not generated to the source.
74     */
75     public boolean isEmpty();
76
77     /** Gets all tags from comment.
78      */
79     public JavaDocTag[] getTags();
80
81     /** Gets all tags of given name
82      */
83     public JavaDocTag[] getTags( String JavaDoc name );
84
85     /** Adds removes or sets tags used in this comment
86      * @param tags the new initializers
87      * @param action {@link #ADD}, {@link #REMOVE}, or {@link #SET}
88      * @exception SourceException if impossible
89      */
90     public void changeTags( JavaDocTag[] tags, int action ) throws SourceException;
91
92     /** Gets all @see tags
93      */
94     public JavaDocTag.See[] getSeeTags();
95
96     /** The JavaDoc of a class.
97     * Class javadoc adds no special tags.
98     */
99     public static interface Class extends JavaDoc {
100
101         /** @deprecated Only public by accident. */
102         /* public static final */ long serialVersionUID = 3206093459760846163L;
103     }
104
105     /** The JavaDoc of a field.
106     * <p>Currently adds special @SerialField tag
107     */
108     public static interface Field extends JavaDoc {
109         /** Gets SerialField tags.
110         */
111         public JavaDocTag.SerialField[] getSerialFieldTags();
112
113     }
114
115     /** The JavaDoc of a method. Adds two special tags: @para tag and @throws tag.
116     */
117     public static interface Method extends JavaDoc {
118         /** Gets param tags.
119         */
120         public JavaDocTag.Param[] getParamTags();
121
122         /** Gets throws tags.
123         */
124         public JavaDocTag.Throws[] getThrowsTags();
125     }
126
127 }
128
Popular Tags