mirrors/cdt
1
0
Fork 0
mirror of https://github.com/eclipse-cdt/cdt synced 2025-06-07 09:46:02 +02:00
Code Issues Wiki Activity

Cosmetics.

Browse source
This commit is contained in:
Sergey Prigogin 2014-08-27 20:09:11 -07:00
parent 97079f6ad0
commit 35044af3ee
1 changed files with 78 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

151
core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNode.java
View file

@ -38,71 +38,69 @@ public interface IASTNode {
*/ */
withLocations withLocations
} }
public static final IASTNode[] EMPTY_NODE_ARRAY = {}; public static final IASTNode[] EMPTY_NODE_ARRAY = {};
/** /**
* Get the translation unit (master) node that is the ancestor of all nodes * Returns the translation unit (master) node that is the ancestor of all nodes
* in this AST. * in this AST.
* *
* @return <code>IASTTranslationUnit</code> * @return {@code IASTTranslationUnit}
*/ */
public IASTTranslationUnit getTranslationUnit(); public IASTTranslationUnit getTranslationUnit();
/** /**
* Get the location of this node. In cases not involving macro expansions, * Returns the location of this node. In cases not involving macro expansions,
* the IASTNodeLocation[] result will only have one element in it, and it * the IASTNodeLocation[] result will only have one element in it, and it
* will be an IASTFileLocation. * will be an {@link IASTFileLocation}.
* * <p>
* Where the node is completely generated within a macro expansion, * Where the node is completely generated within a macro expansion,
* IASTNodeLocation[] result will have one element in it, and it will be an * IASTNodeLocation[] result will have one element in it, and it will be an
* {@link IASTMacroExpansionLocation}. * {@link IASTMacroExpansionLocation}.
* * <p>
* Nodes that span file context into a macro expansion (and potentially out * Nodes that span file context into a macro expansion (and potentially out
* of the macro expansion again) result in an IASTNodeLocation[] result * of the macro expansion again) result in an IASTNodeLocation[] result
* that is of length > 1. * that is of length > 1.
* * <p>
* We do not provide meaningful node locations for nested macro references * We do not provide meaningful node locations for nested macro references
* (see {@link IASTPreprocessorMacroExpansion#getNestedMacroReferences()}). * (see {@link IASTPreprocessorMacroExpansion#getNestedMacroReferences()}).
* For those, the file location of the enclosing explicit macro reference is * For those, the file location of the enclosing explicit macro reference is
* returned. You can however compute their image-location using * returned. You can however compute their image-location using
* {@link IASTName#getImageLocation()} * {@link IASTName#getImageLocation()}
*/ */
public IASTNodeLocation[] getNodeLocations(); public IASTNodeLocation[] getNodeLocations();
/** /**
* Computes a file location for the node. When the node actually resides in a macro-expansion * Computes a file location for the node. When the node actually resides in a macro-expansion
* the location of the expansion is returned. In case the node spans multiple files the location * the location of the expansion is returned. In case the node spans multiple files the location
* will be in a common root file and will contain the appropriate include directives. * will be in a common root file and will contain the appropriate include directives.
* <p> * <p>
* The method may return <code>null</code> in case the node does not have a file-location. This * The method may return {@code null} in case the node does not have a file-location. This
* is for instance the case for built-in macro names or empty names for anonymous type * is for instance the case for built-in macro names or empty names for anonymous type
* declarations. * declarations.
* *
* @return the mapped file location or <code>null</code>. * @return the mapped file location or {@code null}.
*/ */
public IASTFileLocation getFileLocation(); public IASTFileLocation getFileLocation();
/** /**
* Lightweight check for understanding what file we are in. * Lightweight check for understanding what file we are in.
* *
* @return <code>String</code> absolute path * @return {@code String} absolute path
*/ */
public String getContainingFilename(); public String getContainingFilename();
/** /**
* Lightweight check to see whether this node is part of the root file. * Lightweight check to see whether this node is part of the root file.
* @since 5.0 * @since 5.0
*/ */
public boolean isPartOfTranslationUnitFile(); public boolean isPartOfTranslationUnitFile();
/** /**
* Get the parent node of this node in the tree. * Returns the parent node of this node in the tree.
*
* @return the parent node of this node
*/ */
public IASTNode getParent(); public IASTNode getParent();
/** /**
* Returns the children of this node. * Returns the children of this node.
* @since 5.1 * @since 5.1
@ -110,43 +108,44 @@ public interface IASTNode {
IASTNode[] getChildren(); IASTNode[] getChildren();
/** /**
* Set the parent node of this node in the tree. * Sets the parent node of this node in the tree.
* *
* @param node * @param node {@code IASTNode}
* <code>IASTNode</code>
*/ */
public void setParent(IASTNode node); public void setParent(IASTNode node);
/** /**
* In order to properly understand the relationship between this child node * Describes relationship between this child node and it's parent.
* and it's parent, a node property object is used. *
* * @return {@code ASTNodeProperty}
* @return <code>ASTNodeProperty</code>
*/ */
public ASTNodeProperty getPropertyInParent(); public ASTNodeProperty getPropertyInParent();
/** /**
* Set the parent property of the node. * Sets the parent property of the node.
* *
* @param property * @param property
*/ */
public void setPropertyInParent(ASTNodeProperty property); public void setPropertyInParent(ASTNodeProperty property);
/** /**
* Abstract method to be overridden by all subclasses. Necessary for * Abstract method to be overridden by all subclasses. Necessary for
* visitation of the tree using an <code>ASTVisitor</code>. * visitation of the tree using an {@code ASTVisitor}.
* *
* @param visitor * @param visitor
* @return continue on (true) or quit( false ) * @return continue on (true) or quit (false)
*/ */
public boolean accept(ASTVisitor visitor); public boolean accept(ASTVisitor visitor);
/** /**
* Returns the raw signature of the IASTNode before it is processed by the preprocessor. * Returns the raw signature of the IASTNode before it is processed by the preprocessor.
* *
* Example: * Example:
* <pre>
* #define ONE 1 * #define ONE 1
* int x=ONE; // getRawSignature() for this declaration would return "int x=ONE;" * int x=ONE; // getRawSignature() for this declaration would return "int x=ONE;"
* </pre>
*
* @return the raw signature of the IASTNode before it is processed by the preprocessor * @return the raw signature of the IASTNode before it is processed by the preprocessor
*/ */
public String getRawSignature(); public String getRawSignature();
@ -154,23 +153,25 @@ public interface IASTNode {
/** /**
* Returns whether this node contains the given one. The decision is made * Returns whether this node contains the given one. The decision is made
* purely on location information and therefore the method is fast. * purely on location information and therefore the method is fast.
*
* @param node the node to check * @param node the node to check
* @return whether this node contains the given one. * @return whether this node contains the given one.
* @since 4.0 * @since 4.0
*/ */
public boolean contains(IASTNode node); public boolean contains(IASTNode node);
/** /**
* Returns the tokens that can be found between this node and its left sibling (or the * Returns the tokens that can be found between this node and its left sibling (or the
* beginning of the parent, if there is no left sibling). The tokens are obtained * beginning of the parent, if there is no left sibling). The tokens are obtained
* from the lexer, no preprocessing is performed. * from the lexer, no preprocessing is performed.
* The offsets of the tokens are relative to the file-offset of this node. * The offsets of the tokens are relative to the file-offset of this node.
* <p> <b>Examples</b> looking at the condition of if-statements: * <p>
* <b>Examples</b> looking at the condition of if-statements:
* <pre> * <pre>
* #define IF if * #define IF if
* #define IF_P if ( * #define IF_P if (
* #define IF_P_T if (true * #define IF_P_T if (true
* #define SEMI_IF ; if * #define SEMI_IF ; if
* #define IF_COND if (true) * #define IF_COND if (true)
* void test() { * void test() {
* if (true) {} // leading syntax: 'if (' * if (true) {} // leading syntax: 'if ('
@ -180,11 +181,12 @@ public interface IASTNode {
* SEMI_IF (true) {} // throws ExpansionOverlapsBoundaryException * SEMI_IF (true) {} // throws ExpansionOverlapsBoundaryException
* IF_COND // throws ExpansionOverlapsBoundaryException * IF_COND // throws ExpansionOverlapsBoundaryException
* </pre> * </pre>
* @return a chain of tokens or <code>null</code>, if there are none. *
* @return a chain of tokens or {@code null}, if there are none.
* @throws ExpansionOverlapsBoundaryException if one of the boundaries of the leading syntax is * @throws ExpansionOverlapsBoundaryException if one of the boundaries of the leading syntax is
* overlapped by a macro-expansion. * overlapped by a macro-expansion.
* @throws UnsupportedOperationException if invoked on preprocessor nodes, or nodes that are not * @throws UnsupportedOperationException if invoked on preprocessor nodes, or nodes that are not
* part of a translation unit. * part of a translation unit.
* @since 5.1 * @since 5.1
*/ */
public IToken getLeadingSyntax() throws ExpansionOverlapsBoundaryException, public IToken getLeadingSyntax() throws ExpansionOverlapsBoundaryException,
@ -195,22 +197,26 @@ public interface IASTNode {
* end of the parent, if there is no right sibling). The tokens are obtained from the lexer, * end of the parent, if there is no right sibling). The tokens are obtained from the lexer,
* no preprocessing is performed. * no preprocessing is performed.
* The offsets of the tokens are relative to the file-offset of the end of this node. * The offsets of the tokens are relative to the file-offset of the end of this node.
* <p> For examples see {@link #getLeadingSyntax()}. * <p>
* @return a chain of tokens or <code>null</code>, if there are none. * For examples see {@link #getLeadingSyntax()}.
*
* @return a chain of tokens or {@code null}, if there are none.
* @throws ExpansionOverlapsBoundaryException if one of the boundaries of the trailing syntax is * @throws ExpansionOverlapsBoundaryException if one of the boundaries of the trailing syntax is
* overlapped by a macro-expansion. * overlapped by a macro-expansion.
* @throws UnsupportedOperationException if invoked on preprocessor nodes, or nodes that are not * @throws UnsupportedOperationException if invoked on preprocessor nodes, or nodes that are not
* part of a translation unit. * part of a translation unit.
* @since 5.1 * @since 5.1
*/ */
public IToken getTrailingSyntax() throws ExpansionOverlapsBoundaryException, UnsupportedOperationException; public IToken getTrailingSyntax() throws ExpansionOverlapsBoundaryException, UnsupportedOperationException;
/** /**
* Returns the tokens that make up this node. The tokens are obtained from the lexer, * Returns the tokens that make up this node. The tokens are obtained from the lexer,
* no preprocessing is performed. * no preprocessing is performed.
* The offsets of the tokens are relative to the file-offset of the beginning of this node. * The offsets of the tokens are relative to the file-offset of the beginning of this node.
* <p> For examples see {@link #getLeadingSyntax()}. * <p>
* @return a chain of tokens or <code>null</code>, if there are none. * For examples see {@link #getLeadingSyntax()}.
*
* @return a chain of tokens or {@code null}, if there are none.
* @throws ExpansionOverlapsBoundaryException if one of the boundaries of the node is * @throws ExpansionOverlapsBoundaryException if one of the boundaries of the node is
* overlapped by a macro-expansion. * overlapped by a macro-expansion.
* @throws UnsupportedOperationException if invoked on preprocessor nodes, or nodes that are not * @throws UnsupportedOperationException if invoked on preprocessor nodes, or nodes that are not
@ -218,7 +224,7 @@ public interface IASTNode {
* @since 5.1 * @since 5.1
*/ */
public IToken getSyntax() throws ExpansionOverlapsBoundaryException; public IToken getSyntax() throws ExpansionOverlapsBoundaryException;
/** /**
* Returns true if this node is frozen, false otherwise. * Returns true if this node is frozen, false otherwise.
* If the node is frozen then any attempt to call a method that changes * If the node is frozen then any attempt to call a method that changes
@ -226,28 +232,27 @@ public interface IASTNode {
* @since 5.1 * @since 5.1
*/ */
public boolean isFrozen(); public boolean isFrozen();
/** /**
* Returns false if this node was parsed in an inactive code branch. * Returns false if this node was parsed in an inactive code branch.
* @since 5.1 * @since 5.1
*/ */
public boolean isActive(); public boolean isActive();
/** /**
* Returns a mutable copy of the tree rooted at this node. The following postconditions hold: * Returns a mutable copy of the tree rooted at this node. The following postconditions hold:
* * <pre>
* <code>
* copy.getParent() == null * copy.getParent() == null
* copy.getPropertyInParent() == null * copy.getPropertyInParent() == null
* copy.isFrozen() == false * copy.isFrozen() == false
* </code> * </pre>
* *
* Preprocessor nodes do not currently support being copied. * Preprocessor nodes do not currently support being copied.
* *
* Implicit name nodes are not copied, instead they can be regenerated if required. * Implicit name nodes are not copied, instead they can be regenerated if required.
* * <p>
* Calling this method is equivalent * Calling this method is equivalent to {@code copy(CopyStyle.withoutLocations)}.
* *
* @since 5.1 * @since 5.1
* @throws UnsupportedOperationException * @throws UnsupportedOperationException
* if this node or one of its descendants does not support copying * if this node or one of its descendants does not support copying
@ -256,17 +261,17 @@ public interface IASTNode {
/** /**
* Returns a mutable copy of the tree rooted at this node. The following postconditions hold: * Returns a mutable copy of the tree rooted at this node. The following postconditions hold:
* *
* <code> * <pre>
* copy.getParent() == null * copy.getParent() == null
* copy.getPropertyInParent() == null * copy.getPropertyInParent() == null
* copy.isFrozen() == false * copy.isFrozen() == false
* </code> * </pre>
* *
* Preprocessor nodes do not currently support being copied. * Preprocessor nodes do not currently support being copied.
* *
* Implicit name nodes are not copied, instead they can be regenerated if required. * Implicit name nodes are not copied, instead they can be regenerated if required.
* *
* @param style * @param style
* {@link CopyStyle} create a copy with or without locations. Please see * {@link CopyStyle} create a copy with or without locations. Please see
* {@link CopyStyle} for restrictions on copies with Locations. * {@link CopyStyle} for restrictions on copies with Locations.