add documentation to include, fixes #163

lib/liquid/tags/include.rb

@@ -1,7 +1,22 @@
 module Liquid
+
+  # Include allows templates to relate with other templates
+  #
+  # Simply include another template:
+  #
+  #   {% include 'product' %}
+  #
+  # Include a template with a local variable:
+  #
+  #   {% include 'product' with products[0] %}
+  #
+  # Include a template for a collection:
+  #
+  #   {% include 'product' for products %}
+  #
   class Include < Tag
     Syntax = /(#{QuotedFragment}+)(\s+(?:with|for)\s+(#{QuotedFragment}+))?/o
-  
+
     def initialize(tag_name, markup, tokens)
       if markup =~ Syntax
 
@@ -19,14 +34,14 @@ module Liquid
 
       super
     end
-  
+
     def parse(tokens)
     end
-    
+
     def render(context)
       partial = load_cached_partial(context)
       variable = context[@variable_name || @template_name[1..-2]]
-      
+
       context.stack do
         @attributes.each do |key, value|
           context[key] = context[value]
@@ -43,7 +58,7 @@ module Liquid
         end
       end
     end
-   
+
     private
       def load_cached_partial(context)
         cached_partials = context.registers[:cached_partials] || {}
@@ -61,7 +76,7 @@ module Liquid
 
       def read_template_from_file_system(context)
         file_system = context.registers[:file_system] || Liquid::Template.file_system
-      
+
         # make read_template_file call backwards-compatible.
         case file_system.method(:read_template_file).arity
         when 1
@@ -74,5 +89,5 @@ module Liquid
       end
   end
 
-  Template.register_tag('include', Include)  
+  Template.register_tag('include', Include)
 end