Add contract for getChild/getParent

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java

@@ -24,6 +24,16 @@ import net.sourceforge.pmd.lang.dfa.DataFlowNode;
  * <li>Location metadata: eg {@link #getBeginLine()}, {@link #getBeginColumn()}
  * </ul>
  *
+ * <p>It is assumed in many places that the {@link #getChild(int)} and {@link #getParent()}
+ * method return a node of the same type than this node. For example,
+ * no JSP node should have a Java node as its child. Embedding nodes from
+ * different languages will not be done via these methods, and conforming
+ * implementations should ensure, that every node returned by these methods
+ * are indeed of the same type. Possibly, a type parameter will be added to
+ * the Node interface in 7.0.0 to enforce it at compile-time.
+ *
+ * <p>Note: I'm pretty sure Apex doesn't respect this invariant with its comment nodes.
+ *
  * <p>A number of methods are deprecated and will be removed in 7.0.0.
  * Most of them are implementation details that clutter this API and
  * make implementation more difficult. Some methods prefixed with {@code jjt}

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/TokenBasedNode.java

@@ -7,20 +7,23 @@ package net.sourceforge.pmd.lang.ast;
 /**
  * A {@link Node} that can provide access to the underlying
  * {@linkplain GenericToken tokens} produced by the lexer.
+ * Not all nodes do, as some are produced from external parsers.
  */
 public interface TokenBasedNode<T extends GenericToken> extends Node {
 
     /**
      * Returns the first token producing this node.
-     * This is not a special token.
+     * This is not a special token. Never null.
      */
+    // @NotNull
     T getFirstToken();
 
 
     /**
      * Returns the last token producing this node.
-     * This is not a special token.
+     * This is not a special token. Never null.
      */
+    // @NotNull
     T getLastToken();