Document custom renderers

fredemmott · fredemmott · commit 93efbebdd265 · 2017-02-20T22:31:24.000-08:00
diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml
@@ -8,6 +8,7 @@
   items:
   - id: hack-builder-blocks
   - id: hack-builder-keys-and-values
+  - id: hack-builder-custom-renderers
 
 # n title:, 1 items: per title:, n id: per items:
 # - title: A
diff --git a/docs/_docs/hack-builder/custom-renderers.md b/docs/_docs/hack-builder/custom-renderers.md
@@ -0,0 +1,78 @@
+---
+docid: hack-builder-custom-renderers
+title: Custom Renderers
+layout: docs
+permalink: /docs/hack-builder/custom-renderers/
+---
+
+There are 3 main ways to implement custom rendering:
+
+ - Pre-process your values to code, then use `HackBuilderValues::literal()` or 
+   `HackBuilderKeys::literal()`
+ - use `HackBuilderValues::lambda()` or `HackBuilderKeys::lambda()`
+ - create classes that implement `IHackBuilderValueRenderer` or
+   `IHackBuilderKeyRenderer`
+
+Pre-processing
+--------------
+
+Pre-process the values so that the keys/values are the literal code you want
+instead:
+
+``` php
+<?hh
+
+$map = Map { /* ... */ };
+$processed = Map { };
+foreach ($map as $k => $v) {
+  $processed[my_render_function($k)] = $v;
+}
+$builder
+  ->addValue(
+    $map,
+    HackBuilderValues::map(
+      HackBuilderKeys::literal(),
+      HackBuilderValues::export(),
+    ),
+  );
+```
+
+This is usually the right approach for a single value, but not the most readable
+for multiple values, eg for collections.
+
+Lambdas
+-------
+
+The lambda takes an `IHackCodegenConfig` and the value; the value can be used
+to create a `HackCodegenFactory` if neccessary, though as there's usually one
+in scope, it's usually unneeded.
+
+``` php
+<?hh
+
+$map = Map { /* ... */ };
+$builder
+  ->addValue(
+    $map,
+    HackBuilderValues::map(
+      HackBuilderKeys::lambda(
+        ($_config, $v) ==> my_render_function($v),
+      ),
+      HackBuilderValues::export(),
+    ),
+  );
+```
+
+This can be the right choice when the same renderer is needed for many values but
+in few places.
+
+Custom Renderer Classes
+-----------------------
+
+If you are using the same renderer in multiple places, you can implement the
+`IHackBuilderKeysRenderer<T>` or `IHackBuilderValuesRenderer<T>` interfaces;
+this is the same way the built-ins are implemented.
+
+While it's possible to implement both in the same class, it's usually better
+not to so that the hack typechecker has more visibility into argument order
+mistakes for collections.
diff --git a/docs/_docs/hack-builder/keys-and-values.md b/docs/_docs/hack-builder/keys-and-values.md
@@ -16,7 +16,7 @@ This is based on the `IHackBuilderValueRenderer<T>` interface, which provides
 `public function render(IHackCodegenConfig $config, T $input): string` which
 returns PHP code.
 
-Basic Built-ins
+Basic Built-Ins
 ---------------
 
 Hack Codegen provides several implementation of this interface, accessed via
