net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/dom/TagElement.java

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