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

   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 package net.sourceforge.phpdt.core.dom;
  12
  13 /**
  14  * Abstract base class for all AST nodes that represent comments.
  15  * There are exactly three kinds of comment:
  16  * line comments ({@link LineComment}),
  17  * block comments ({@link BlockComment}), and
  18  * doc comments ({@link Javadoc}).
  19  * <p>
  20  * <pre>
  21  * Comment:
  22  *     LineComment
  23  *     BlockComment
  24  *     Javadoc
  25  * </pre>
  26  * </p>
  27  *
  28  * @since 3.0
  29  */
  30 public abstract class Comment extends ASTNode {
  31
  32         /**
  33          * Alternate root node, or <code>null</code> if none.
  34          * Initially <code>null</code>.
  35          */
  36         private ASTNode alternateRoot = null;
  37
  38         /**
  39          * Creates a new AST node for a comment owned by the given AST.
  40          * <p>
  41          * N.B. This constructor is package-private.
  42          * </p>
  43          *
  44          * @param ast the AST that is to own this node
  45          */
  46         Comment(AST ast) {
  47                 super(ast);
  48         }
  49
  50         /**
  51          * Returns whether this comment is a block comment
  52          * (<code>BlockComment</code>).
  53          *
  54          * @return <code>true</code> if this is a block comment, and
  55          *    <code>false</code> otherwise
  56          */
  57         public final boolean isBlockComment() {
  58                 return (this instanceof BlockComment);
  59         }
  60
  61         /**
  62          * Returns whether this comment is a line comment
  63          * (<code>LineComment</code>).
  64          *
  65          * @return <code>true</code> if this is a line comment, and
  66          *    <code>false</code> otherwise
  67          */
  68         public final boolean isLineComment() {
  69                 return (this instanceof LineComment);
  70         }
  71
  72         /**
  73          * Returns whether this comment is a doc comment
  74          * (<code>Javadoc</code>).
  75          *
  76          * @return <code>true</code> if this is a doc comment, and
  77          *    <code>false</code> otherwise
  78          */
  79         public final boolean isDocComment() {
  80                 return (this instanceof Javadoc);
  81         }
  82
  83         /**
  84          * Returns the root AST node that this comment occurs
  85          * within, or <code>null</code> if none (or not recorded).
  86          * <p>
  87          * Typically, the comment nodes created while parsing a compilation
  88          * unit are not considered descendents of the normal AST
  89          * root, namely an {@link CompilationUnit}. Instead, these
  90          * comment nodes exist outside the normal AST and each is
  91          * a root in its own right. This optional property provides
  92          * a well-known way to navigate from the comment to the
  93          * compilation unit in such cases. Note that the alternate root
  94          * property is not one of the comment node's children. It is simply a
  95          * reference to a node.
  96          * </p>
  97          *
  98          * @return the alternate root node, or <code>null</code>
  99          * if none
 100          * @see #setAlternateRoot(ASTNode)
 101          */
 102         public final ASTNode getAlternateRoot() {
 103                 return this.alternateRoot;
 104         }
 105
 106         /**
 107          * Returns the root AST node that this comment occurs
 108          * within, or <code>null</code> if none (or not recorded).
 109          * <p>
 110          * </p>
 111          *
 112          * @param root the alternate root node, or <code>null</code>
 113          * if none
 114          * @see #getAlternateRoot()
 115          */
 116         public final void setAlternateRoot(ASTNode root) {
 117                 // alternate root is *not* considered a structural property
 118                 // but we protect them nevertheless
 119                 checkModifiable();
 120                 this.alternateRoot = root;
 121         }
 122
 123         /* (omit javadoc for this method)
 124          * Method declared on ASTNode.
 125          */
 126         int memSize() {
 127                 return BASE_NODE_SIZE + 1 * 4;
 128         }
 129 }