More tests and compiler API docs

docs/compiler-api.md

@@ -556,7 +556,7 @@ builder.selfInvokingFunction(
 Or, without params and args:
 
 ```javascript
-builder.selfInvokingFunction([
+builder.selfInvokingFunction(null, null, [
         builder.vars(['foo']),
         builder.assignment('foo', builder.literal('bar'))
     ])
@@ -569,10 +569,57 @@ builder.selfInvokingFunction([
 }())
 ```
 
-### slot()
+### selfInvokingFunction(body)
+
+Equivalent to `selfInvokingFunction(null, null, body)`.
+
+### slot(onDone)
+
+Returns a node that defers generating code until everything else is done. This can be helpful in situations where a fragment of code is not known until the rest of the code is generated.
+
+As an example, the [TemplateRoot](../compiler/ast/TemplateRoot.js) node uses a slot to defer generating the static variables section of the compiled template. Not until all of the nodes have generated code is it known which static variables need to be added at the top of the compiled template.
+
+```javascript
+builder.program([
+    builder.slot((slot, generator) => {
+        slot.setContent(generator.builder.vars(vars));
+    }),
+    builder.node(function(node, generator) {
+        vars.push({
+            id: 'foo',
+            init: generator.builder.literal('abc')
+        });
+    }),
+    builder.node(function(node, generator) {
+        vars.push({
+            id: 'bar',
+            init: generator.builder.literal(123)
+        });
+    })
+])
+
+// Output code:
+var foo = "abc",
+    bar = 123;
+```
 
 ### strictEquality(left, right)
 
+Returns a node that generates the following code:
+
+```javascript
+<left> === <right>
+```
+
+For example:
+
+```javascript
+builder.strictEquality('a', 'b')
+
+// Output code:
+a === b
+```
+
 ### templateRoot(body)
 
 ### text(argument, escape)

test/fixtures/codegen/autotest/selfInvokingFunction-null-args/expected.js

@@ -0,0 +1,5 @@
+(function() {
+  var foo;
+
+  foo = "bar";
+}())

test/fixtures/codegen/autotest/selfInvokingFunction-null-args/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+module.exports = function(builder) {
+    return builder.selfInvokingFunction(
+        null,
+        null,
+        [
+            builder.vars(['foo']),
+            builder.assignment('foo', builder.literal('bar'))
+        ]);
+};

test/fixtures/codegen/autotest/slot-with-statements/expected.js

@@ -0,0 +1,6 @@
+a = "abc";
+
+var foo = "abc",
+    bar = 123;
+
+b = "def";

test/fixtures/codegen/autotest/slot-with-statements/index.js

@@ -0,0 +1,25 @@
+'use strict';
+
+module.exports = function(builder) {
+    var vars = [];
+
+    return builder.program([
+            builder.assignment('a', builder.literal('abc')),
+            builder.slot((slot, generator) => {
+                slot.setContent(generator.builder.vars(vars));
+            }),
+            builder.node(function(node, generator) {
+                vars.push({
+                    id: 'foo',
+                    init: generator.builder.literal('abc')
+                });
+            }),
+            builder.node(function(node, generator) {
+                vars.push({
+                    id: 'bar',
+                    init: generator.builder.literal(123)
+                });
+            }),
+            builder.assignment('b', builder.literal('def'))
+        ]);
+};

test/fixtures/codegen/autotest/slot-with-writes-nested/expected.js

@@ -0,0 +1,8 @@
+if (true) {
+  out.w("BEFORE - Hello World");
+
+  var foo = "abc",
+      bar = 123;
+
+  out.w("AFTER - Hello World");
+}

test/fixtures/codegen/autotest/slot-with-writes-nested/index.js

@@ -0,0 +1,29 @@
+'use strict';
+
+module.exports = function(builder) {
+    var vars = [];
+
+    var varsSlot = builder.slot((slot, generator) => {
+        slot.setContent(generator.builder.vars(vars));
+    });
+
+    return builder.program([
+            builder.ifStatement('true', [
+                builder.text(builder.literal('BEFORE - Hello World')),
+                varsSlot,
+                builder.node(function(node, generator) {
+                    vars.push({
+                        id: 'foo',
+                        init: builder.literal('abc')
+                    });
+                }),
+                builder.node(function(node, generator) {
+                    vars.push({
+                        id: 'bar',
+                        init: builder.literal(123)
+                    });
+                }),
+                builder.text(builder.literal('AFTER - Hello World'))
+            ])
+        ]);
+};

test/fixtures/codegen/autotest/slot-with-writes/expected.js

@@ -0,0 +1,6 @@
+out.w("BEFORE - Hello World");
+
+var foo = "abc",
+    bar = 123;
+
+out.w("AFTER - Hello World");

test/fixtures/codegen/autotest/slot-with-writes/index.js

@@ -0,0 +1,27 @@
+'use strict';
+
+module.exports = function(builder) {
+    var vars = [];
+
+    var varsSlot = builder.slot((slot, generator) => {
+        slot.setContent(generator.builder.vars(vars));
+    });
+
+    return builder.program([
+            builder.text(builder.literal('BEFORE - Hello World')),
+            varsSlot,
+            builder.node(function(node, generator) {
+                vars.push({
+                    id: 'foo',
+                    init: builder.literal('abc')
+                });
+            }),
+            builder.node(function(node, generator) {
+                vars.push({
+                    id: 'bar',
+                    init: builder.literal(123)
+                });
+            }),
+            builder.text(builder.literal('AFTER - Hello World'))
+        ]);
+};

test/fixtures/codegen/autotest/slot/expected.js

@@ -0,0 +1,2 @@
+var foo = "abc",
+    bar = 123;

test/fixtures/codegen/autotest/slot/index.js

@@ -0,0 +1,23 @@
+'use strict';
+
+module.exports = function(builder) {
+    var vars = [];
+
+    return builder.program([
+            builder.slot((slot, generator) => {
+                slot.setContent(generator.builder.vars(vars));
+            }),
+            builder.node(function(node, generator) {
+                vars.push({
+                    id: 'foo',
+                    init: generator.builder.literal('abc')
+                });
+            }),
+            builder.node(function(node, generator) {
+                vars.push({
+                    id: 'bar',
+                    init: generator.builder.literal(123)
+                });
+            })
+        ]);
+};

test/fixtures/codegen/autotest/strictEquality/expected.js

@@ -0,0 +1 @@
+a === b

test/fixtures/codegen/autotest/strictEquality/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = function(builder) {
+    return builder.strictEquality('a', 'b');
+};