TagElement


1   /*******************************************************************************
2    * Copyright (c) 2004, 2006 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  /**
18   * AST node for a tag within a doc comment.
19   * Tag elements nested within another tag element are called
20   * inline doc tags.
21   * <pre>
22   * TagElement:
23   *     [ <b>@</b> Identifier ] { DocElement }
24   * DocElement:
25   *     TextElement
26   *     Name
27   *     MethodRef
28   *     MemberRef
29   *     <b>{</b> TagElement <b>}</b>
30   * </pre>
31   * 
32   * @see Javadoc
33   * @since 3.0
34   */
35  public final class TagElement extends ASTNode implements IDocElement {
36  
37      /**
38       * The "tagName" structural property of this node type.
39       * 
40       * @since 3.0
41       */
42      public static final SimplePropertyDescriptor TAG_NAME_PROPERTY = 
43          new SimplePropertyDescriptor(TagElement.class, "tagName", String  .class, OPTIONAL); //$NON-NLS-1$
44      
45      /**
46       * The "fragments" structural property of this node type.
47       * @since 3.0
48       */
49      public static final ChildListPropertyDescriptor FRAGMENTS_PROPERTY = 
50          new ChildListPropertyDescriptor(TagElement.class, "fragments", IDocElement.class, CYCLE_RISK); //$NON-NLS-1$
51  
52      /**
53       * A list of property descriptors (element type: 
54       * {@link StructuralPropertyDescriptor}),
55       * or null if uninitialized.
56       * @since 3.0
57       */
58      private static final List   PROPERTY_DESCRIPTORS;
59      
60      static {
61          List   propertyList = new ArrayList  (3);
62          createPropertyList(TagElement.class, propertyList);
63          addProperty(TAG_NAME_PROPERTY, propertyList);
64          addProperty(FRAGMENTS_PROPERTY, propertyList);
65          PROPERTY_DESCRIPTORS = reapPropertyList(propertyList);
66      }
67      
68      /**
69       * Returns a list of structural property descriptors for this node type.
70       * Clients must not modify the result.
71       * 
72       * @param apiLevel the API level; one of the
73       * <code>AST.JLS*</code> constants
74       * @return a list of property descriptors (element type: 
75       * {@link StructuralPropertyDescriptor})
76       * @since 3.0
77       */
78      public static List   propertyDescriptors(int apiLevel) {
79          return PROPERTY_DESCRIPTORS;
80      }
81      
82      /**
83       * Standard doc tag name (value {@value}).
84       */
85      public static final String   TAG_AUTHOR = "@author"; //$NON-NLS-1$
86  
87      /**
88       * Standard inline doc tag name (value {@value}).
89       * <p>
90       * Note that this tag first appeared in J2SE 5.
91       * </p>
92       * @since 3.1
93       */
94      public static final String   TAG_CODE = "@code"; //$NON-NLS-1$
95  
96      /**
97       * Standard doc tag name (value {@value}).
98       */
99      public static final String   TAG_DEPRECATED = "@deprecated"; //$NON-NLS-1$
100 
101     /**
102      * Standard inline doc tag name (value {@value}).
103      */
104     public static final String   TAG_DOCROOT = "@docRoot"; //$NON-NLS-1$
105 
106     /**
107      * Standard doc tag name (value {@value}).
108      */
109     public static final String   TAG_EXCEPTION = "@exception"; //$NON-NLS-1$
110 
111     /**
112      * Standard inline doc tag name (value {@value}).
113      */
114     public static final String   TAG_INHERITDOC = "@inheritDoc"; //$NON-NLS-1$
115 
116     /**
117      * Standard inline doc tag name (value {@value}).
118      */
119     public static final String   TAG_LINK = "@link"; //$NON-NLS-1$
120 
121     /**
122      * Standard inline doc tag name (value {@value}).
123      */
124     public static final String   TAG_LINKPLAIN = "@linkplain"; //$NON-NLS-1$
125 
126     /**
127      * Standard inline doc tag name (value {@value}).
128      * <p>
129      * Note that this tag first appeared in J2SE 5.
130      * </p>
131      * @since 3.1
132      */
133     public static final String   TAG_LITERAL = "@literal"; //$NON-NLS-1$
134 
135     /**
136      * Standard doc tag name (value {@value}).
137      */
138     public static final String   TAG_PARAM = "@param"; //$NON-NLS-1$
139 
140     /**
141      * Standard doc tag name (value {@value}).
142      */
143     public static final String   TAG_RETURN = "@return"; //$NON-NLS-1$
144 
145     /**
146      * Standard doc tag name (value {@value}).
147      */
148     public static final String   TAG_SEE = "@see"; //$NON-NLS-1$
149 
150     /**
151      * Standard doc tag name (value {@value}).
152      */
153     public static final String   TAG_SERIAL = "@serial"; //$NON-NLS-1$
154 
155     /**
156      * Standard doc tag name (value {@value}).
157      */
158     public static final String   TAG_SERIALDATA= "@serialData"; //$NON-NLS-1$
159 
160     /**
161      * Standard doc tag name (value {@value}).
162      */
163     public static final String   TAG_SERIALFIELD= "@serialField"; //$NON-NLS-1$
164 
165     /**
166      * Standard doc tag name (value {@value}).
167      */
168     public static final String   TAG_SINCE = "@since"; //$NON-NLS-1$
169 
170     /**
171      * Standard doc tag name (value {@value}).
172      */
173     public static final String   TAG_THROWS = "@throws"; //$NON-NLS-1$
174 
175     /**
176      * Standard inline doc tag name (value {@value}).
177      */
178     public static final String   TAG_VALUE= "@value"; //$NON-NLS-1$
179 
180     /**
181      * Standard doc tag name (value {@value}).
182      */
183     public static final String   TAG_VERSION = "@version"; //$NON-NLS-1$
184 
185     /**
186      * The tag name, or null if none; defaults to null.
187      */
188     private String   optionalTagName = null;
189     
190     /**
191      * The list of doc elements (element type: <code>IDocElement</code>). 
192      * Defaults to an empty list.
193      */
194     private ASTNode.NodeList fragments = 
195         new ASTNode.NodeList(FRAGMENTS_PROPERTY);
196 
197     /**
198      * Creates a new AST node for a tag element owned by the given AST.
199      * The new node has no name and an empty list of fragments.
200      * <p>
201      * N.B. This constructor is package-private; all subclasses must be 
202      * declared in the same package; clients are unable to declare 
203      * additional subclasses.
204      * </p>
205      * 
206      * @param ast the AST that is to own this node
207      */
208     TagElement(AST ast) {
209         super(ast);
210     }
211     
212     /* (omit javadoc for this method)
213      * Method declared on ASTNode.
214      */
215     final List   internalStructuralPropertiesForType(int apiLevel) {
216         return propertyDescriptors(apiLevel);
217     }
218     
219     /* (omit javadoc for this method)
220      * Method declared on ASTNode.
221      */
222     final Object   internalGetSetObjectProperty(SimplePropertyDescriptor property, boolean get, Object   value) {
223         if (property == TAG_NAME_PROPERTY) {
224             if (get) {
225                 return getTagName();
226             } else {
227                 setTagName((String  ) value);
228                 return null;
229             }
230         }
231         // allow default implementation to flag the error
232         return super.internalGetSetObjectProperty(property, get, value);
233     }
234 
235     /* (omit javadoc for this method)
236      * Method declared on ASTNode.
237      */
238     final List   internalGetChildListProperty(ChildListPropertyDescriptor property) {
239         if (property == FRAGMENTS_PROPERTY) {
240             return fragments();
241         }
242         // allow default implementation to flag the error
243         return super.internalGetChildListProperty(property);
244     }
245     
246     /* (omit javadoc for this method)
247      * Method declared on ASTNode.
248      */
249     final int getNodeType0() {
250         return TAG_ELEMENT;
251     }
252 
253     /* (omit javadoc for this method)
254      * Method declared on ASTNode.
255      */
256     ASTNode clone0(AST target) {
257         TagElement result = new TagElement(target);
258         result.setSourceRange(this.getStartPosition(), this.getLength());
259         result.setTagName(getTagName());
260         result.fragments().addAll(ASTNode.copySubtrees(target, fragments()));
261         return result;
262     }
263     
264     /* (omit javadoc for this method)
265      * Method declared on ASTNode.
266      */
267     final boolean subtreeMatch0(ASTMatcher matcher, Object   other) {
268         // dispatch to correct overloaded match method
269         return matcher.match(this, other);
270     }
271 
272     /* (omit javadoc for this method)
273      * Method declared on ASTNode.
274      */
275     void accept0(ASTVisitor visitor) {
276         boolean visitChildren = visitor.visit(this);
277         if (visitChildren) {
278             acceptChildren(visitor, this.fragments);
279         }
280         visitor.endVisit(this);
281     }
282 
283     /**
284      * Returns this node's tag name, or <code>null</code> if none.
285      * For top level doc tags such as parameter tags, the tag name
286      * includes the "@" character ("@param").
287      * For inline doc tags such as link tags, the tag name
288      * includes the "@" character ("@link").
289      * The tag name may also be <code>null</code>; this is used to
290      * represent the material at the start of a doc comment preceding
291      * the first explicit tag.
292      *
293      * @return the tag name, or <code>null</code> if none
294      */ 
295     public String   getTagName() {
296         return this.optionalTagName;
297     }
298     
299     /**
300      * Sets the tag name of this node to the given value.
301      * For top level doc tags such as parameter tags, the tag name
302      * includes the "@" character ("@param").
303      * For inline doc tags such as link tags, the tag name
304      * includes the "@" character ("@link").
305      * The tag name may also be <code>null</code>; this is used to
306      * represent the material at the start of a doc comment preceding
307      * the first explicit tag.
308      *
309      * @param tagName the tag name, or <code>null</code> if none
310      */ 
311     public void setTagName(String   tagName) {
312         preValueChange(TAG_NAME_PROPERTY);
313         this.optionalTagName = tagName;
314         postValueChange(TAG_NAME_PROPERTY);
315     }
316         
317     /**
318      * Returns the live list of fragments in this tag element. 
319      * <p>
320      * The fragments cover everything following the tag name
321      * (or everything if there is no tag name), and generally omit
322      * embedded line breaks (and leading whitespace on new lines,
323      * including any leading "*"). {@link org.eclipse.jdt.core.dom.TagElement}
324      * nodes are used to represent tag elements (e.g., "@link")
325      * nested within this tag element. 
326      * </p>
327      * <p>
328      * Here are some typical examples:
329      * <ul>
330      * <li>"@see Foo#bar()" - TagElement with tag name "@see";
331      * fragments() contains a single MethodRef node</li>
332      * <li>"@param args the program arguments" -
333      * TagElement with tag name "@param";
334      * 2 fragments: SimpleName ("args"), TextElement
335      * (" the program arguments")</li>
336      * <li>"@return See {&#64;link #foo foo} instead." - 
337      * TagElement with tag name "@return";
338      * 3 fragments: TextElement ("See "),
339      * TagElement (for "&#64;link #foo foo"),
340      * TextElement (" instead.")</li>
341      * </ul>
342      * The use of Name, MethodRef, and MemberRef nodes within
343      * tag elements allows these fragments to be queried for
344      * binding information.
345      * </p>
346      * <p>
347      * Adding and removing nodes from this list affects this node
348      * dynamically. The nodes in this list may be of various
349      * types, including {@link TextElement}, 
350      * {@link org.eclipse.jdt.core.dom.TagElement}, {@link Name}, 
351      * {@link MemberRef}, and {@link MethodRef}.
352      * Clients should assume that the list of types may grow in
353      * the future, and write their code to deal with unexpected
354      * nodes types. However, attempts to add a non-proscribed type
355      * of node will trigger an exception.
356      * 
357      * @return the live list of doc elements in this tag element
358      * (element type: <code>ASTNode</code>)
359      */ 
360     public List   fragments() {
361         return this.fragments;
362     }
363 
364     /**
365      * Returns whether this tag element is nested within another
366      * tag element. Nested tag elements appears enclosed in 
367      * "{" and "}"; certain doc tags, including "@link" and
368      * "@linkplain" are only meaningful as nested tags.
369      * Top-level (i.e., non-nested) doc tags begin on a new line;
370      * certain doc tags, including "@param" and
371      * "@see" are only meaningful as top-level tags.
372      * <p>
373      * This convenience methods checks to see whether the parent
374      * of this node is of type {@link org.eclipse.jdt.core.dom.TagElement}.
375      * </p>
376      * 
377      * @return <code>true</code> if this node is a nested tag element,
378      * and false if this node is either parented by a doc comment node
379      * ({@link Javadoc}), or is unparented
380      */
381     public boolean isNested() {
382         return (getParent() instanceof TagElement);
383     }
384     
385     /* (omit javadoc for this method)
386      * Method declared on ASTNode.
387      */
388     int memSize() {
389         int size = BASE_NODE_SIZE + 2 * 4 + stringSize(this.optionalTagName);
390         return size;
391     }
392     
393     /* (omit javadoc for this method)
394      * Method declared on ASTNode.
395      */
396     int treeSize() {
397         return memSize() + this.fragments.listSize();
398     }
399 }
400
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags