Javadoc


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.jdt.core.dom;
13  
14  import java.util.ArrayList  ;
15  import java.util.List  ;
16  
17  import org.eclipse.jdt.core.compiler.InvalidInputException;
18  import org.eclipse.jdt.internal.compiler.parser.Scanner;
19  import org.eclipse.jdt.internal.compiler.parser.TerminalTokens;
20  
21  /**
22   * AST node for a Javadoc-style doc comment.
23   * <pre>
24   * Javadoc:
25   *   <b>/** </b> { TagElement } <b>*</b><b>/</b>
26   * </pre>
27   * 
28   * @since 2.0
29   */
30  public class Javadoc extends Comment {
31      
32      /**
33       * The "comment" structural property of this node type (JLS2 API only).
34       * @since 3.0
35       * @deprecated Replaced by {@link #TAGS_PROPERTY} in the JLS3 API.
36       */
37      public static final SimplePropertyDescriptor COMMENT_PROPERTY = 
38          new SimplePropertyDescriptor(Javadoc.class, "comment", String  .class, MANDATORY); //$NON-NLS-1$
39      
40      /**
41       * The "tags" structural property of this node type.
42       * @since 3.1
43       */
44      public static final ChildListPropertyDescriptor TAGS_PROPERTY = 
45          new ChildListPropertyDescriptor(Javadoc.class, "tags", TagElement.class, CYCLE_RISK); //$NON-NLS-1$
46  
47      
48      /**
49       * A list of property descriptors (element type: 
50       * {@link StructuralPropertyDescriptor}),
51       * or null if uninitialized.
52       * @since 3.0
53       */
54      private static final List   PROPERTY_DESCRIPTORS_2_0;
55      
56      /**
57       * A list of property descriptors (element type: 
58       * {@link StructuralPropertyDescriptor}),
59       * or null if uninitialized.
60       * @since 3.1
61       */
62      private static final List   PROPERTY_DESCRIPTORS_3_0;
63      
64      static {
65          List   properyList = new ArrayList  (3);
66          createPropertyList(Javadoc.class, properyList);
67          addProperty(COMMENT_PROPERTY, properyList);
68          addProperty(TAGS_PROPERTY, properyList);
69          PROPERTY_DESCRIPTORS_2_0 = reapPropertyList(properyList);
70          
71          properyList = new ArrayList  (2);
72          createPropertyList(Javadoc.class, properyList);
73          addProperty(TAGS_PROPERTY, properyList);
74          PROPERTY_DESCRIPTORS_3_0 = reapPropertyList(properyList);
75      }
76  
77      /**
78       * Returns a list of structural property descriptors for this node type.
79       * Clients must not modify the result.
80       * 
81       * @param apiLevel the API level; one of the
82       * <code>AST.JLS*</code> constants
83       * @return a list of property descriptors (element type: 
84       * {@link StructuralPropertyDescriptor})
85       * @since 3.0
86       */
87      public static List   propertyDescriptors(int apiLevel) {
88          if (apiLevel == AST.JLS2_INTERNAL) {
89              return PROPERTY_DESCRIPTORS_2_0;
90          } else {
91              return PROPERTY_DESCRIPTORS_3_0;
92          }
93      }
94      
95      /**
96       * Canonical minimal doc comment.
97       * @since 3.0
98       */
99      private static final String   MINIMAL_DOC_COMMENT = "/** */";//$NON-NLS-1$
100 
101     /**
102      * The doc comment string, including opening and closing comment 
103      * delimiters; defaults to a minimal Javadoc comment.
104      * @deprecated The comment string was replaced in the 3.0 release
105      * by a representation of the structure of the doc comment.
106      * For backwards compatibility, it is still funcational as before.
107      */
108     private String   comment = MINIMAL_DOC_COMMENT;
109     
110     /**
111      * The list of tag elements (element type: <code>TagElement</code>). 
112      * Defaults to an empty list.
113      * @since 3.0
114      */
115     private ASTNode.NodeList tags = 
116         new ASTNode.NodeList(TAGS_PROPERTY);
117 
118     /**
119      * Creates a new AST node for a doc comment owned by the given AST.
120      * The new node has an empty list of tag elements (and, for backwards
121      * compatability, an unspecified, but legal, doc comment string).
122      * <p>
123      * N.B. This constructor is package-private; all subclasses must be 
124      * declared in the same package; clients are unable to declare 
125      * additional subclasses.
126      * </p>
127      * 
128      * @param ast the AST that is to own this node
129      */
130     Javadoc(AST ast) {
131         super(ast);
132     }
133     
134     /* (omit javadoc for this method)
135      * Method declared on ASTNode.
136      */
137     final List   internalStructuralPropertiesForType(int apiLevel) {
138         return propertyDescriptors(apiLevel);
139     }
140     
141     /* (omit javadoc for this method)
142      * Method declared on ASTNode.
143      */
144     final Object   internalGetSetObjectProperty(SimplePropertyDescriptor property, boolean get, Object   value) {
145         if (property == COMMENT_PROPERTY) {
146             if (get) {
147                 return getComment();
148             } else {
149                 setComment((String  ) value);
150                 return null;
151             }
152         }
153         // allow default implementation to flag the error
154         return super.internalGetSetObjectProperty(property, get, value);
155     }
156 
157     /* (omit javadoc for this method)
158      * Method declared on ASTNode.
159      */
160     final List   internalGetChildListProperty(ChildListPropertyDescriptor property) {
161         if (property == TAGS_PROPERTY) {
162             return tags();
163         }
164         // allow default implementation to flag the error
165         return super.internalGetChildListProperty(property);
166     }
167     
168     /* (omit javadoc for this method)
169      * Method declared on ASTNode.
170      */
171     final int getNodeType0() {
172         return JAVADOC;
173     }
174 
175     /* (omit javadoc for this method)
176      * Method declared on ASTNode.
177      */
178     ASTNode clone0(AST target) {
179         Javadoc result = new Javadoc(target);
180         result.setSourceRange(this.getStartPosition(), this.getLength());
181         if (this.ast.apiLevel == AST.JLS2_INTERNAL) {
182             result.setComment(getComment());
183         }
184         result.tags().addAll(ASTNode.copySubtrees(target, tags()));
185         return result;
186     }
187     
188     /* (omit javadoc for this method)
189      * Method declared on ASTNode.
190      */
191     final boolean subtreeMatch0(ASTMatcher matcher, Object   other) {
192         // dispatch to correct overloaded match method
193         return matcher.match(this, other);
194     }
195 
196     /* (omit javadoc for this method)
197      * Method declared on ASTNode.
198      */
199     void accept0(ASTVisitor visitor) {
200         boolean visitChildren = visitor.visit(this);
201         if (visitChildren) {
202             // visit children in normal left to right reading order
203             acceptChildren(visitor, this.tags);
204         }
205         visitor.endVisit(this);
206     }
207 
208     /**
209      * Returns the doc comment string, including the starting
210      * and ending comment delimiters, and any embedded line breaks.
211      * 
212      * @return the doc comment string
213      * @exception UnsupportedOperationException if this operation is used in
214      * an AST later than JLS2
215      * @deprecated The comment string was replaced in the 3.0 release
216      * by a representation of the structure of the doc comment.
217      * See {@link #tags() tags}.
218      */
219     public String   getComment() {
220         supportedOnlyIn2();
221         return this.comment;
222     }
223 
224     /**
225      * Sets or clears the doc comment string. The documentation
226      * string must include the starting and ending comment delimiters,
227      * and any embedded line breaks.
228      * 
229      * @param docComment the doc comment string
230      * @exception IllegalArgumentException if the Java comment string is invalid
231      * @exception UnsupportedOperationException if this operation is used in
232      * an AST later than JLS2
233      * @deprecated The comment string was replaced in the 3.0 release
234      * by a representation of the structure of the doc comment.
235      * See {@link #tags() tags}.
236      */
237     public void setComment(String   docComment) {
238         supportedOnlyIn2();
239         if (docComment == null) {
240             throw new IllegalArgumentException  ();
241         }
242         char[] source = docComment.toCharArray();
243         Scanner scanner = this.ast.scanner;
244         scanner.resetTo(0, source.length);
245         scanner.setSource(source);
246         try {
247             int token;
248             boolean onlyOneComment = false;
249             while ((token = scanner.getNextToken()) != TerminalTokens.TokenNameEOF) {
250                 switch(token) {
251                     case TerminalTokens.TokenNameCOMMENT_JAVADOC :
252                         if (onlyOneComment) {
253                             throw new IllegalArgumentException  ();
254                         }
255                         onlyOneComment = true;
256                         break;
257                     default:
258                         onlyOneComment = false;
259                 }
260             }
261             if (!onlyOneComment) {
262                 throw new IllegalArgumentException  ();
263             }
264         } catch (InvalidInputException e) {
265             throw new IllegalArgumentException  ();
266         }
267         preValueChange(COMMENT_PROPERTY);
268         this.comment = docComment;
269         postValueChange(COMMENT_PROPERTY);
270     }
271         
272     /**
273      * Returns the live list of tag elements that make up this doc 
274      * comment.
275      * <p>
276      * The tag elements cover everything except the starting and ending
277      * comment delimiters, and generally omit leading whitespace 
278      * (including a leading "*") and embedded line breaks.
279      * The first tag element of a typical doc comment represents
280      * all the material before the first explicit doc tag; this
281      * first tag element has a <code>null</code> tag name and
282      * generally contains 1 or more {@link TextElement}s,
283      * and possibly interspersed with tag elements for nested tags
284      * like "{@link String String}".
285      * Subsequent tag elements represent successive top-level doc
286      * tag (e.g., "@param", "@return", "@see").
287      * </p>
288      * <p>
289      * Adding and removing nodes from this list affects this node
290      * dynamically.
291      * </p>
292      * 
293      * @return the live list of tag elements in this doc comment
294      * (element type: <code>TagElement</code>)
295      * @since 3.0
296      */ 
297     public List   tags() {
298         return this.tags;
299     }
300     
301     /* (omit javadoc for this method)
302      * Method declared on ASTNode.
303      */
304     int memSize() {
305         int size = super.memSize() + 2 * 4;
306         if (this.comment != MINIMAL_DOC_COMMENT) {
307             // anything other than the default string takes space
308             size += stringSize(this.comment);
309         }
310         return size;
311     }
312     
313     /* (omit javadoc for this method)
314      * Method declared on ASTNode.
315      */
316     int treeSize() {
317         return memSize() + this.tags.listSize();
318     }
319 }
320
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags