Merge pull request #1719 from jmm/internals-docs2

Internals documentation

CONTRIBUTING.md

@@ -12,6 +12,8 @@
    <strong><a href="#dependencies">Dependencies</a></strong>
    |
    <strong><a href="#code-standards">Code Standards</a></strong>
+   |
+   <strong><a href="#internals">Internals</a></strong>
 </p>
 
 ----
@@ -173,3 +175,6 @@ your [`$PATH`](http://unix.stackexchange.com/questions/26047/how-to-correctly-ad
  * **Declaration**
    * No unused variables
    * No pollution of global variables and prototypes
+
+#### Internals
+Please see [`/doc`](/doc) for internals documentation relevant to developing babel.

doc/index.md

@@ -0,0 +1,4 @@
+This is a collection of documentation about babel internals, for use in development of babel.
+
+# [Properties of nodes](/doc/node-props.md)
+These are properties babel stores in AST node objects for internal use, as opposed to properties that are part of the AST spec (ESTree at the time of this writing).

doc/node-props.md

@@ -0,0 +1,11 @@
+# Properties of nodes
+These are properties babel stores in AST node objects for internal use, as opposed to properties that are part of the AST spec (ESTree at the time of this writing).
+
+## `_blockHoist`
+`node._blockHoist != null` triggers the [block-hoist transformer](/src/babel/transformation/transformers/internal/block-hoist.js). Value should be `true` or an integer in the range `0..3`. `true` is equivalent to `2`. The value indicates whether the node should be hoisted and to what degree. See the source code for more detailed information.
+
+## `_paths`
+Stores a representation of a node's position in the tree and relationship to other nodes.
+
+## `shadow`
+A truthy value on a function node triggers the [shadow-functions transformer](/src/babel/transformation/transformers/internal/shadow-functions.js), which transforms the node so that it references (or inherits) `arguments` and `this` from the parent scope. It is invoked for arrow functions, for example.