Document block constructs in HackBuilder

fredemmott · fredemmott · commit 046c8604829d · 2017-02-20T19:52:54.000-08:00
diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml
@@ -4,6 +4,9 @@
   - id: overview-config-and-factory
   - id: overview-hack-builder
   - id: overview-definitions
+- title: Hack Builder
+  items:
+  - id: hack-builder-blocks
 
 # n title:, 1 items: per title:, n id: per items:
 # - title: A
diff --git a/docs/_docs/hack-builder/blocks.md b/docs/_docs/hack-builder/blocks.md
@@ -0,0 +1,84 @@
+---
+docid: hack-builder-blocks
+title: Blocks
+layout: docs
+permalink: /docs/hack-builder/blocks/
+---
+
+All forms of blocks can be created with the fundamental constructs - eg an `if`
+block can be created with:
+
+``` php
+<?hh
+$builder
+  ->addLine('if ($condition) {')
+  ->indent()
+  /* do other stuff */
+  ->unindent()
+  ->ensureNewLine()
+  ->addLine('}');
+```
+
+This is verbose and hard to scan through; methods are provided that help with both
+for common structures.
+
+If Statements
+-------------
+
+``` php
+<?hh
+$builder
+  ->startIfBlock($condition)
+  /* do stuff */
+  ->addElseIfBlock($condition)
+  /* do other stuff */
+  ->addElseBlock()
+  /* do weird stuff */
+  ->endIfBlock();
+```
+
+Switch Statements
+-----------------
+
+``` php
+<?hh
+$builder
+  ->startSwitch('$var')
+  ->addCase('foo')
+  /* do stuff */
+  ->breakCase()
+  ->addCase('bar')
+  /* do stuff */
+  ->returnCase('$x', HackBuilderValues::literal())
+  ->addDefault()
+  ->breakCase()
+  ->endSwitch();
+```
+
+For-Each Loops
+--------------
+
+``` php
+<?hh
+$builder
+  ->startForeachLoop('$list', '$key', '$value')
+  /* do stuff */
+  ->endForeachLoop();
+```
+
+The second parameter can be null.
+
+Try-Catch Blocks
+----------------
+
+``` php
+<?hh
+$builder
+  ->startTryBlock()
+  /* do stuff */
+  ->addCatchBlock('SomeException', '$e')
+  /* do stuff */
+  ->addFinallyBlock()
+  /* do stuff */
+  ->endTryBlock();
+```
diff --git a/docs/_docs/overview/hack-builder.md b/docs/_docs/overview/hack-builder.md
@@ -45,6 +45,8 @@ As readable code is a goal of Hack Codegen, several whitespace helpers are provi
  - `->addMultilineCall($call, $args)`: either renders the call all on one line, or with
    one argument on one line, depending on if it can fit within the maximum line length
 
+Finally, you can get the generated code as a string by calling `->getCode()`.
+
 Values
 ------
 
@@ -76,10 +78,11 @@ Blocks
 Helpers are provided for common block constructs - eg:
 
 ``` php
+<?hh
 $builder
   ->startIf('$condition')
   ->addLine('doStuff();')
   ->endIf()
 ```
 
-See the `HackBuilder` source for a complete list.
+See [the reference documentation](/hack-codegen/docs/hack-builder/blocks/) for details.
