more ast docs

Author: basarat

SUMMARY.md

@@ -33,3 +33,4 @@
 * [TypeScript Compiler](docs/compiler/overview.md)
   * [Program](docs/compiler/program.md)
   * [AST](docs/compiler/ast.md)
+    * [TIP: Visit Children](docs/compiler/ast-tip-children.md)

docs/compiler/ast-tip-children.md

@@ -0,0 +1,24 @@
+### AST Tip: Visit Children
+
+There is a utility function `ts.forEachChild` that allows you to visit all the child nodes of any Node in the AST.
+
+Here is simplified snippet of the source code to demonstrate how it functions:
+
+```ts
+
+export function forEachChild<T>(node: Node, cbNode: (node: Node) => T, cbNodeArray?: (nodes: Node[]) => T): T {
+        if (!node) {
+            return;
+        }
+        switch (node.kind) {
+            case SyntaxKind.BinaryExpression:
+                return visitNode(cbNode, (<BinaryExpression>node).left) ||
+                    visitNode(cbNode, (<BinaryExpression>node).operatorToken) ||
+                    visitNode(cbNode, (<BinaryExpression>node).right);
+            case SyntaxKind.IfStatement:
+                return visitNode(cbNode, (<IfStatement>node).expression) ||
+                    visitNode(cbNode, (<IfStatement>node).thenStatement) ||
+                    visitNode(cbNode, (<IfStatement>node).elseStatement);
+```
+
+Basically it checks `node.kind` and based on that assumes an interface offered by the `node` and calls the `cbNode` on the children.

docs/compiler/ast.md

@@ -1,8 +1,13 @@
 ## Node
 The basic building block of the Abstract Syntax Tree (AST). In general node represent non-terminals in the language grammar; some terminals are kept in the tree such as identifiers and literals.
 
-## Note on AST description
-Two key things make up an AST node definition. Its `SyntaxKind` which identifies it within the AST and its `interface`, the API the node provides  when instantiated for the AST.
+Two key things make up an AST node documentation. Its `SyntaxKind` which identifies it within the AST and its `interface`, the API the node provides  when instantiated for the AST.
+
+Here are a few key `interface Node` members:
+* `TextRange` members that identify the node's `start` and `end` in the source file.
+* `parent?: Node` the parent of the node in the AST.
+
+There are other additional members for node flags and modifiers etc. that you can lookup by searching `interface Node` in the source code but the ones we mentioned are vital for node traversal.
 
 ## SourceFile
 

docs/compiler/overview.md

@@ -7,13 +7,14 @@ It is split into the follow key parts:
 * Binder (`bindder.ts`)
 * Checker (`checker.ts`)
 * Emitter (`emitter.ts`)
+* Program (`program.ts`)
 
 Each of these get their own unique files in the source. These parts will be explained later on in this chapter.
 
 There are a few additional files in the TypeScript compiler that provide utilities to many of these key portions:
 
 ## File: Utilities
-core.ts : core utilities used by the TypeScript compiler
+`core.ts` : core utilities used by the TypeScript compiler
 
 ## File: Key Data Structures
 `types.ts` contains key data structures and interfaces uses throughout the compiler. Here is a sampling of a few key ones:
@@ -22,10 +23,9 @@ The AST node type is identified by the `SyntaxKind` enum.
 * `TypeChecker`
 This is the interface provided by the TypeChecker.
 * `CompilerHost`
-This is used by the `Program` to interact with the `System`
+This is used by the `Program` to interact with the `System`.
+* `Node`
+A AST node.
 
 ## File: System
 All interaction of the TypeScript compiler with the operating system goes through a `System` interface. Both the interface and its implementations (`WScript` and `Node`) are defined in `system.ts`. You can think of it as the *Operating Environment* (OE).
-
-## File: Program
-The compilation context ([a concept we covered previously](docs/project/compilation-context.md)) is represented within the TypeScript compiler as a `Program`.

docs/compiler/program.md

@@ -1,5 +1,8 @@
 ## Program
 
+The compilation context ([a concept we covered previously](docs/project/compilation-context.md)) is represented within the TypeScript compiler as a `Program`. It consists of `SourceFile`s and compiler options.
+
+
 ### Usage of `CompilerHost`
 Its interaction mechanism with the OE:
 
@@ -11,7 +14,4 @@ There are other users of `System` as well (e.g. tests).
 
 ### SourceFile
 
-* `SyntaxKind.SourceFile`
-* `interface SourceFile`.
-
-The `program` consists of a bunch of source files. A `sourceFile` is actually a top-level AST node as well (`SyntaxKind.SourceFile`). Instances implement `interface SourceFile`.
+The program provides an API to get the Source Files `getSourceFiles(): SourceFile[];`. Each is represented as a root-level node for an AST (called `SourceFile`).