Add comments to public libraries

pkg/analyzer/lib/dart/ast/ast.dart

Index: pkg/analyzer/lib/dart/ast/ast.dart
diff --git a/pkg/analyzer/lib/dart/ast/ast.dart b/pkg/analyzer/lib/dart/ast/ast.dart
index 1237fd1d7148a7b6325d6e7197886b2da6013b4a..31dd785b9fea45fc28c4ffb4b007819945292787 100644
--- a/pkg/analyzer/lib/dart/ast/ast.dart
+++ b/pkg/analyzer/lib/dart/ast/ast.dart
@@ -2,6 +2,38 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+/**
+ * Defines the AST model. The AST (Abstract Syntax Tree) model describes the
+ * syntactic (as opposed to semantic) structure of Dart code. The semantic
+ * structure of the code is modeled by the
+ * [element model](../element/element.dart).
+ *
+ * An AST consists of nodes (instances of a subclass of [AstNode]). The nodes
+ * are organized in a tree structure in which the children of a node are the
+ * smaller syntactic units from which the node is composed. For example, a
+ * binary expression consists of two sub-expressions (the operands) and an
+ * operator. The two expressions are represented as nodes. The operator is not
+ * represented as a node.
+ *
+ * The AST is constructed by the parser based on the sequence of tokens produced
+ * by the scanner. Most nodes provide direct access to the tokens used to build
+ * the node. For example, the token for the operator in a binary expression can
+ * be accessed from the node representing the binary expression.
+ *
+ * While any node can theoretically be the root of an AST structure, almost all
+ * of the AST structures known to the analyzer have a [CompilationUnit] as the
+ * root of the structure. A compilation unit represents all of the Dart code in
+ * a single file.
+ *
+ * An AST can be either unresolved or resolved. When an AST is unresolved
+ * certain properties will not have been computed and the accessors for those
+ * properties will return `null`. The documentation for those getters should
+ * describe that this is a possibility.
+ *
+ * When an AST is resolved, the identifiers in the AST will be associated with
+ * the elements that they refer to and every expression in the AST will have a
+ * type associated with it.
+ */
 library analyzer.dart.ast.ast;
 
 import 'package:analyzer/dart/element/element.dart';