Add docs for templates

doc/3_Code_generation.markdown

@@ -57,3 +57,207 @@ abstract class SomeClass extends SomeOtherClass implements A\Few, Interfaces
     }
 }
 ```
+
+Templates
+---------
+
+Additionally it is possible to generate code from reusable templates.
+
+As an example consider the following template, which defines a general getter/setter sceleton in terms of a property
+`__name__` and its `__type__`:
+
+```php
+<?php
+
+class GetterSetterTemplate
+{
+    /**
+     * @var __type__ The __name__
+     */
+    protected $__name__;
+
+    /**
+     * Gets the __name__.
+     *
+     * @return __type__ The __name__
+     */
+    public function get__Name__() {
+        return $this->__name__;
+    }
+
+    /**
+     * Sets the __name__.
+     *
+     * @param __type__ $__name__ The new __name__
+     */
+    public function set__Name__($__name__) {
+        $this->__name__ = $__name__;
+    }
+}
+```
+
+Using this template we can easily create a class with multiple properties and their respective getters and setters:
+
+```php
+<?php
+
+// $templateString contains the above template
+$template = new PHPParser_Template($parser, $templateString);
+
+// We only have to specify the __name__ placeholder, as the
+// capitalized __Name__ placeholder is automatically created
+$properties = [
+    ['name' => 'title',     'type' => 'string'],
+    ['name' => 'body',      'type' => 'string'],
+    ['name' => 'author',    'type' => 'User'],
+    ['name' => 'timestamp', 'type' => 'DateTime'],
+];
+
+$class = $factory->class('BlogPost')->implement('Post');
+
+foreach ($properties as $propertyPlaceholders) {
+    $stmts = $template->getStmts($propertyPlaceholders);
+
+    $class->addStmts(
+        // $stmts contains all statements from the template. So [0] fetches the class statement
+        // and ->stmts retrieves the methods.
+        $stmts[0]->stmts
+    );
+}
+
+echo $prettyPrinter->prettyPrint(array($class->getNode()));
+```
+
+The result would look roughly like this:
+
+```php
+<?php
+
+class BlogPost implements Post
+{
+    /**
+     * @var string The title
+     */
+    protected $title;
+
+    /**
+     * @var string The body
+     */
+    protected $body;
+
+    /**
+     * @var User The author
+     */
+    protected $author;
+
+    /**
+     * @var DateTime The timestamp
+     */
+    protected $timestamp;
+
+    /**
+     * Gets the title.
+     *
+     * @return string The title
+     */
+    public function getTitle()
+    {
+        return $this->title;
+    }
+
+    /**
+     * Sets the title.
+     *
+     * @param string $title The new title
+     */
+    public function setTitle($title)
+    {
+        $this->title = $title;
+    }
+
+    /**
+     * Gets the body.
+     *
+     * @return string The body
+     */
+    public function getBody()
+    {
+        return $this->body;
+    }
+
+    /**
+     * Sets the body.
+     *
+     * @param string $body The new body
+     */
+    public function setBody($body)
+    {
+        $this->body = $body;
+    }
+
+    /**
+     * Gets the author.
+     *
+     * @return User The author
+     */
+    public function getAuthor()
+    {
+        return $this->author;
+    }
+
+    /**
+     * Sets the author.
+     *
+     * @param User $author The new author
+     */
+    public function setAuthor($author)
+    {
+        $this->author = $author;
+    }
+
+    /**
+     * Gets the timestamp.
+     *
+     * @return DateTime The timestamp
+     */
+    public function getTimestamp()
+    {
+        return $this->timestamp;
+    }
+
+    /**
+     * Sets the timestamp.
+     *
+     * @param DateTime $timestamp The new timestamp
+     */
+    public function setTimestamp($timestamp)
+    {
+        $this->timestamp = $timestamp;
+    }
+}
+```
+
+When using multiple templates it is easier to manage them on the filesystem. They can be loaded using the
+`TemplateLoader`:
+
+```php
+<?php
+
+// We'll store our templates in ./templates and give them a .php suffix
+$loader = new PHPParser_TemplateLoader($parser, './templates', '.php');
+
+// loads ./templates/GetterSetter.php
+$getterSetterTemplate = $loader->load('GetterSetter');
+
+// loads ./templates/Collection.php
+$collectionTemplate = $loader->load('Collection');
+
+// The use of a suffix is optional. The following code for example is equivalent:
+$loader = new PHPParser_TemplateLoader($parser, './templates');
+
+// loads ./templates/GetterSetter.php
+$getterSetterTemplate = $loader->load('GetterSetter.php');
+
+// loads ./templates/Collection.php
+$collectionTemplate = $loader->load('Collection.php');
+```