diff --git a/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTName.java b/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTName.java
index a48c80657f8..e7f86e40b4d 100644
--- a/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTName.java
+++ b/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTName.java
@@ -21,12 +21,15 @@ package org.eclipse.cdt.core.dom.ast;
  */
 public interface IASTName extends IASTNode {
 	
+	/**
+	 * Constant sentinel. 
+	 */
 	public static final IASTName[] EMPTY_NAME_ARRAY = new IASTName[0];
 
 	/**
 	 * Return the semantic object this name is referring to.
 	 * 
-	 * @return binding
+	 * @return <code>IBinding</code> binding
 	 */
 	public IBinding resolveBinding();
 	
@@ -34,9 +37,14 @@ public interface IASTName extends IASTNode {
 	 * Return a list of bindings in the scope of the name that have the
 	 * name as a prefix.
 	 * 
-	 * @return bindings that start with this name
+	 * @return <code>IBinding []</code> bindings that start with this name
 	 */
 	public IBinding[] resolvePrefix();
 	
+	/**
+	 * Return a char array representation of the name.
+	 * 
+	 * @return ~ toString().toCharArray()
+	 */
 	public char[] toCharArray();
 }
diff --git a/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNamedTypeSpecifier.java b/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNamedTypeSpecifier.java
index 39ff8f2b7ef..77409d866a0 100644
--- a/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNamedTypeSpecifier.java
+++ b/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNamedTypeSpecifier.java
@@ -11,19 +11,30 @@
 package org.eclipse.cdt.core.dom.ast;
 
 /**
- * Represents the use of a typedef name in an decl specifier.
+ * Represents the use of a typedef name in an decl specifier in C.
+ * Also used for class/struct/union names in C.
  * 
  * @author Doug Schaefer
  */
 public interface IASTNamedTypeSpecifier extends IASTDeclSpecifier {
 
+	/**
+	 * <code>NAME</code> describes the relationship between an <code>IASTNamedTypeSpecifier</code> and its nested <code>IASTName</code>.
+	 */
 	public static final ASTNodeProperty NAME = new ASTNodeProperty( "Name"); //$NON-NLS-1$
 
     /**
+     * Get the name. 
+     * 
 	 * @return the typedef name.
 	 */
 	public IASTName getName();
 	
+	/**
+	 * Set the name.
+	 * 
+	 * @param name
+	 */
 	public void setName( IASTName name );
 	
 }
diff --git a/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNode.java b/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNode.java
index 9e6c404da73..f057c9f8db4 100644
--- a/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNode.java
+++ b/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNode.java
@@ -11,35 +11,75 @@
 package org.eclipse.cdt.core.dom.ast;
 
 /**
- * This is the root node in the physical AST. A physical node represents
- * a chunk of text in the source program.
+ * This is the root node in the physical AST. A physical node represents a chunk
+ * of text in the source program.
  * 
  * @author Doug Schaefer
  */
 public interface IASTNode {
 
-    public IASTTranslationUnit getTranslationUnit();
-    public IASTNodeLocation[] getNodeLocations();
-    
+	/**
+	 * Get the translation unit (master) node that is the ancestor of all nodes
+	 * in this AST.
+	 * 
+	 * @return <code>IASTTranslationUnit</code>
+	 */
+
+	public IASTTranslationUnit getTranslationUnit();
+
+	/**
+	 * Get the location of this node. In cases not involving macro expansions,
+	 * the IASTNodeLocation [] result will only have one element in it, and it
+	 * will be an IASTFileLocation or subinterface.
+	 * 
+	 * Where the node is completely generated within a macro expansion,
+	 * IASTNodeLocation [] result will have one element in it, and it will be an
+	 * IASTMacroExpansion.
+	 * 
+	 * Nodes that span file context into a macro expansion (and potentially out
+	 * of the macro expansion again) result in an IASTNodeLocation [] result
+	 * that is of length > 1.
+	 * 
+	 * @return <code>IASTNodeLocation []</code>
+	 */
+	public IASTNodeLocation[] getNodeLocations();
+
 	/**
 	 * Get the parent node of this node in the tree.
 	 * 
 	 * @return the parent node of this node
 	 */
 	public IASTNode getParent();
-	
-	public void setParent( IASTNode node );
 
 	/**
-	 * In order to properly understand the relationship between this child
-	 * node and it's parent, a node property object is used.
+	 * Set the parent node of this node in the tree. 
 	 * 
-	 * @return
+	 * @param node <code>IASTNode</code>
+	 */
+	public void setParent(IASTNode node);
+
+	/**
+	 * In order to properly understand the relationship between this child node
+	 * and it's parent, a node property object is used.
+	 * 
+	 * @return <code>ASTNodeProperty</code>
 	 */
 	public ASTNodeProperty getPropertyInParent();
-	
-	public void setPropertyInParent( ASTNodeProperty property );
-	
-	public boolean accept( ASTVisitor visitor );
+
+	/**
+	 * Set the parent property of the node.  
+	 * 
+	 * @param property
+	 */
+	public void setPropertyInParent(ASTNodeProperty property);
+
+	/**
+	 * Abstract method to be overriden by all subclasses.
+	 * Necessary for visitation of the tree using an <code>ASTVisitor</code>.
+	 * 
+	 * @param visitor
+	 * @return continue on (true) or quit( false )
+	 */
+	public boolean accept(ASTVisitor visitor);
 
 }
diff --git a/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNullStatement.java b/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNullStatement.java
index 0ea19672d98..cc5835a835b 100644
--- a/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNullStatement.java
+++ b/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/dom/ast/IASTNullStatement.java
@@ -11,6 +11,9 @@ package org.eclipse.cdt.core.dom.ast;
 
 
 /**
+ * This node represents a null statement. 
+ * ';'
+ * 
  * @author jcamelon
  */
 public interface IASTNullStatement extends IASTStatement {