Merge pull request #41 from nene/ast-spec

Document AST differences from ESTree

README.md

@@ -26,7 +26,7 @@ Significant diversions are expected to occur in the future such as streaming, EB
 
 ### `babylon.parse(code, [options])`
 
-## Options
+### Options
 
 - **allowImportExportEverywhere**: By default, `import` and `export`
   declarations can only appear at a program's top level. Setting this
@@ -45,6 +45,43 @@ Significant diversions are expected to occur in the future such as streaming, EB
 
 - **plugins**: Array containing the plugins that you want to enable.
 
+### Output
+
+Babylon generates AST according to [Babel AST format][].
+It is based on [ESTree spec][] with the following deviations:
+
+- [Literal][] token is replaced with [StringLiteral][], [NumericLiteral][], [BooleanLiteral][], [NullLiteral][], [RegExpLiteral][]
+- [Property][] token is replaced with [ObjectProperty][] and [ObjectMethod][]
+- [MethodDefinition][] is replaced with [ClassMethod][]
+- [Program][] and [BlockStatement][] contain additional `directives` field with [Directive][] and [DirectiveLiteral][]
+
+AST for JSX code is based on [Facebook JSX AST][] with the addition of one node type:
+
+- `JSXText`
+
+[Babel AST format]: https://github.com/babel/babel/blob/master/doc/ast/spec.md
+[ESTree spec]: https://github.com/estree/estree
+
+[Literal]: https://github.com/estree/estree/blob/master/spec.md#literal
+[Property]: https://github.com/estree/estree/blob/master/spec.md#property
+[MethodDefinition]: https://github.com/estree/estree/blob/master/es6.md#methoddefinition
+
+[StringLiteral]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#stringliteral
+[NumericLiteral]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#numericliteral
+[BooleanLiteral]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#booleanliteral
+[NullLiteral]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#nullliteral
+[RegExpLiteral]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#regexpliteral
+[ObjectProperty]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#objectproperty
+[ObjectMethod]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#objectmethod
+[ClassMethod]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#classmethod
+[Program]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#programs
+[BlockStatement]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#blockstatement
+[Directive]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#directive
+[DirectiveLiteral]: https://github.com/babel/babel/blob/master/doc/ast/spec.md#directiveliteral
+
+[Facebook JSX AST]: https://github.com/facebook/jsx/blob/master/AST.md
+
+
 ### Example
 
 ```javascript