From dd0adcc96c555d7fa1dc0a4a711b0594ecba39e6 Mon Sep 17 00:00:00 2001
From: Nikita Popov <nikita.ppv@googlemail.com>
Date: Sat, 27 Jan 2018 18:56:21 +0100
Subject: [PATCH] Move code gen docs to components and improve

Mention non-fluent helper methods.
---
 README.md                                     |  3 +-
 doc/README.md                                 |  3 +-
 .../AST_builders.markdown}                    | 32 ++++++++++++++++---
 3 files changed, 31 insertions(+), 7 deletions(-)
 rename doc/{4_Code_generation.markdown => component/AST_builders.markdown} (64%)

diff --git a/README.md b/README.md
index d90acda..4e0a33a 100644
--- a/README.md
+++ b/README.md
@@ -184,7 +184,6 @@ Documentation
  1. [Introduction](doc/0_Introduction.markdown)
  2. [Usage of basic components](doc/2_Usage_of_basic_components.markdown)
  3. [Other node tree representations](doc/3_Other_node_tree_representations.markdown)
- 4. [Code generation](doc/4_Code_generation.markdown)
 
 Component documentation:
 
@@ -195,6 +194,8 @@ Component documentation:
    * Converting AST back to PHP code
    * Customizing formatting
    * Formatting-preserving code transformations
+ * [AST builders](component/AST_builders.markdown)
+   * Fluent builders for AST nodes
  * [Lexer](doc/component/Lexer.markdown)
    * Lexer options
    * Token and file positions for nodes
diff --git a/doc/README.md b/doc/README.md
index e32cac8..1fe1013 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -7,7 +7,6 @@ Guide
   1. [Introduction](0_Introduction.markdown)
   2. [Usage of basic components](2_Usage_of_basic_components.markdown)
   3. [Other node tree representations](3_Other_node_tree_representations.markdown)
-  4. [Code generation](4_Code_generation.markdown)
 
 Component documentation
 -----------------------
@@ -19,6 +18,8 @@ Component documentation
     * Converting AST back to PHP code
     * Customizing formatting
     * Formatting-preserving code transformations
+  * [AST builders](component/AST_builders.markdown)
+    * Fluent builders for AST nodes
   * [Lexer](component/Lexer.markdown)
     * Lexer options
     * Token and file positions for nodes
diff --git a/doc/4_Code_generation.markdown b/doc/component/AST_builders.markdown
similarity index 64%
rename from doc/4_Code_generation.markdown
rename to doc/component/AST_builders.markdown
index ac9e498..e0fd8e2 100644
--- a/doc/4_Code_generation.markdown
+++ b/doc/component/AST_builders.markdown
@@ -1,9 +1,17 @@
-Code generation
-===============
+AST builders
+============
 
-It is also possible to generate code using the parser, by first creating an Abstract Syntax Tree and then using the
-pretty printer to convert it to PHP code. To simplify code generation, the project comes with builders which allow
-creating node trees using a fluid interface, instead of instantiating all nodes manually. Builders are available for
+When PHP-Parser is used to generate (or modify) code, by first creating an Abstract Syntax Tree and
+then using the [pretty printer](Pretty_printing.markdown) to convert it to PHP code, it can often
+be tedious to manually construct AST nodes. The project provides a number of utilities to simplify
+the construction of common AST nodes.
+
+Fluent builders
+---------------
+
+The library comes with a number of builders, which allow creating node trees using a fluent
+interface. Builders are created using the `BuilderFactory` and the final constructed node is
+accessed through `getNode()`. Fluent builders are available for
 the following syntactic elements:
 
  * namespaces and use statements
@@ -82,3 +90,17 @@ abstract class SomeOtherClass extends SomeClass implements A\Few, \Interfaces
     }
 }
 ```
+
+Additional helper methods
+-------------------------
+
+The `BuilderFactory` also provides a number of additional helper methods, which directly return
+nodes. The following methods are currently available:
+
+ * `val($value)`: Creates an AST node for a literal value like `42` or `[1, 2, 3]`.
+ * `args(array $args)`: Creates an array of function/method arguments, including the required `Arg`
+   wrappers. Also converts literals to AST nodes.
+ * `concat(...$exprs)`: Create a tree of `BinaryOp\Concat` nodes for the given expressions.
+
+These methods may be expanded on an as-needed basis. Please open an issue or PR if a common
+operation is missing.
\ No newline at end of file