doc: Merge/update old Template docs into source [prototypejs#133 stat…

…e:fixed_in_branch]

src/lang/template.js

@@ -14,7 +14,7 @@
  *  expression. The `Template` class provides a much nicer and clearer way of
  *  achieving this formatting.
  *
- *  <h5>Straightforward templates</h5>
+ *  ##### Straightforward templates
  *
  *  The `Template` class uses a basic formatting syntax, similar to what is
  *  used in Ruby. The templates are created from strings that have embedded
@@ -36,7 +36,7 @@
  *      myTemplate.evaluate(show);
  *      // -> "The TV show The Simpsons was created by Matt Groening."
  *
- *  <h5>Templates are meant to be reused</h5>
+ *  ##### Templates are meant to be reused
  *
  *  As the example illustrates, `Template` objects are not tied to specific
  *  data. The data is bound to the template only during the evaluation of the
@@ -60,7 +60,7 @@
  *      // -> Multiply by 0.9478 to convert from kilojoules to BTUs.
  *      // -> Multiply by 1024 to convert from megabytes to gigabytes.
  *
- *  <h5>Escape sequence</h5>
+ *  ##### Escape sequence
  *
  *  There's always the chance that one day you'll need to have a literal in your
  *  template that looks like a symbol, but is not supposed to be replaced. For
@@ -75,7 +75,7 @@
  *      t.evaluate(data);
  *      // -> in Ruby we also use the #{variable} syntax for templates.
  *
- *  <h5>Custom syntaxes</h5>
+ *  ##### Custom syntaxes
  *
  *  The default syntax of the template strings will probably be enough for most
  *  scenarios. In the rare occasion where the default Ruby-like syntax is
@@ -122,6 +122,23 @@ var Template = Class.create({
    *
    *  Applies the template to `object`'s data, producing a formatted string
    *  with symbols replaced by `object`'s corresponding properties.
+   *  
+   *  #####  Examples
+   *  
+   *      var hrefTemplate = new Template('/dir/showAll?lang=#{language}&amp;categ=#{category}&amp;lv=#{levels}');
+   *      var selection = {category: 'books' , language: 'en-US'};
+   *      
+   *      hrefTemplate.evaluate(selection);
+   *      // -> '/dir/showAll?lang=en-US&amp;categ=books&amp;lv='
+   *      
+   *      hrefTemplate.evaluate({language: 'jp', levels: 3, created: '10/12/2005'});
+   *      // -> '/dir/showAll?lang=jp&amp;categ=&amp;lv=3'
+   *      
+   *      hrefTemplate.evaluate({});
+   *      // -> '/dir/showAll?lang=&amp;categ=&amp;lv='
+   *      
+   *      hrefTemplate.evaluate(null);
+   *      // -> error !
   **/
   evaluate: function(object) {
     if (object && Object.isFunction(object.toTemplateReplacements))