Add comments to public libraries

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

 // Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
 // 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';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:analyzer/src/dart/ast/ast.dart';
 import 'package:analyzer/src/dart/element/element.dart' show AuxiliaryElements;
 import 'package:analyzer/src/generated/java_core.dart';
 import 'package:analyzer/src/generated/java_engine.dart';
 import 'package:analyzer/src/generated/scanner.dart';
 import 'package:analyzer/src/generated/source.dart' show LineInfo, Source;
@@ skipping 7964 matching lines @@
   /**
    * Return the 'yield' keyword.
    */
   Token get yieldKeyword;
 
   /**
    * Return the 'yield' keyword to the given [token].
    */
   void set yieldKeyword(Token token);
 }