From 163290b5d4927d422b987725a989e9e45aef4583 Mon Sep 17 00:00:00 2001
From: Oliver Steele <steele@osteele.com>
Date: Mon, 10 Jul 2017 09:38:46 -0400
Subject: [PATCH] docs

---
 cmd/liquid/main.go        |  9 +++++++
 engine.go                 | 14 +++++------
 engine_test.go            | 51 +++++++++++++++++++++++++++++++++++++--
 expression/expressions.go |  4 ++-
 parser/parser.go          |  7 +-----
 5 files changed, 69 insertions(+), 16 deletions(-)

diff --git a/cmd/liquid/main.go b/cmd/liquid/main.go
index 96a13d0..5cbbc93 100644
--- a/cmd/liquid/main.go
+++ b/cmd/liquid/main.go
@@ -1,3 +1,12 @@
+// Package main defines a command-line interface to the Liquid engine.
+//
+// This command intended for testing and bug reports.
+//
+// Examples:
+//
+// 	echo '{{ "Hello " | append: "World" }}' | liquid
+// 	liquid source.tpl
+
 package main
 
 import (
diff --git a/engine.go b/engine.go
index f4887fe..0a4f166 100644
--- a/engine.go
+++ b/engine.go
@@ -71,8 +71,8 @@ func (e *Engine) RegisterTag(name string, td Renderer) {
 }
 
 // ParseTemplate creates a new Template using the engine configuration.
-func (e *Engine) ParseTemplate(text []byte) (*Template, error) {
-	root, err := e.cfg.Compile(string(text))
+func (e *Engine) ParseTemplate(source []byte) (*Template, error) {
+	root, err := e.cfg.Compile(string(source))
 	if err != nil {
 		return nil, err
 	}
@@ -80,17 +80,17 @@ func (e *Engine) ParseTemplate(text []byte) (*Template, error) {
 }
 
 // ParseAndRender parses and then renders the template.
-func (e *Engine) ParseAndRender(text []byte, b Bindings) ([]byte, error) {
-	tpl, err := e.ParseTemplate(text)
+func (e *Engine) ParseAndRender(source []byte, b Bindings) ([]byte, error) {
+	tpl, err := e.ParseTemplate(source)
 	if err != nil {
 		return nil, err
 	}
 	return tpl.Render(b)
 }
 
-// ParseAndRenderString is a convenience wrapper for ParseAndRender, that has string input and output.
-func (e *Engine) ParseAndRenderString(text string, b Bindings) (string, error) {
-	bs, err := e.ParseAndRender([]byte(text), b)
+// ParseAndRenderString is a convenience wrapper for ParseAndRender, that takes string input and returns a string.
+func (e *Engine) ParseAndRenderString(source string, b Bindings) (string, error) {
+	bs, err := e.ParseAndRender([]byte(source), b)
 	if err != nil {
 		return "", err
 	}
diff --git a/engine_test.go b/engine_test.go
index c52b6bb..81fcb36 100644
--- a/engine_test.go
+++ b/engine_test.go
@@ -41,13 +41,13 @@ func TestEngine_ParseAndRenderString(t *testing.T) {
 
 func Example() {
 	engine := NewEngine()
-	template := `<h1>{{ page.title }}</h1>`
+	source := `<h1>{{ page.title }}</h1>`
 	bindings := map[string]interface{}{
 		"page": map[string]string{
 			"title": "Introduction",
 		},
 	}
-	out, err := engine.ParseAndRenderString(template, bindings)
+	out, err := engine.ParseAndRenderString(source, bindings)
 	if err != nil {
 		log.Fatalln(err)
 	}
@@ -55,6 +55,32 @@ func Example() {
 	// Output: <h1>Introduction</h1>
 }
 
+func ExampleEngine_ParseAndRenderString() {
+	engine := NewEngine()
+	source := `{{ hello | capitalize | append: " Mundo" }}`
+	bindings := map[string]interface{}{"hello": "hola"}
+	out, err := engine.ParseAndRenderString(source, bindings)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	fmt.Println(out)
+	// Output: Hola Mundo
+}
+func ExampleEngine_ParseTemplate() {
+	engine := NewEngine()
+	source := `{{ hello | capitalize | append: " Mundo" }}`
+	bindings := map[string]interface{}{"hello": "hola"}
+	tpl, err := engine.ParseTemplate([]byte(source))
+	if err != nil {
+		log.Fatalln(err)
+	}
+	out, err := tpl.RenderString(bindings)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	fmt.Println(out)
+	// Output: Hola Mundo
+}
 func ExampleEngine_RegisterFilter() {
 	engine := NewEngine()
 	engine.RegisterFilter("has_prefix", strings.HasPrefix)
@@ -69,6 +95,27 @@ func ExampleEngine_RegisterFilter() {
 	fmt.Println(out)
 	// Output: true
 }
+func ExampleEngine_RegisterFilter_optional_argument() {
+	engine := NewEngine()
+	// func(a, b int) int) would default the second argument to zero.
+	// Then we can't tell the difference between {{ n | inc }} and
+	// {{ n | inc: 0 }}. A function in the parameter list has a special
+	// meaning as a default parameter.
+	engine.RegisterFilter("inc", func(a int, b func(int) int) int {
+		return a + b(1)
+	})
+	template := `10 + 1 = {{ m | inc }}; 20 + 5 = {{ n | inc: 5 }}`
+	bindings := map[string]interface{}{
+		"m": 10,
+		"n": "20",
+	}
+	out, err := engine.ParseAndRenderString(template, bindings)
+	if err != nil {
+		log.Fatalln(err)
+	}
+	fmt.Println(out)
+	// Output: 10 + 1 = 11; 20 + 5 = 25
+}
 
 func ExampleEngine_RegisterTag() {
 	engine := NewEngine()
diff --git a/expression/expressions.go b/expression/expressions.go
index d91e294..f3ade7b 100644
--- a/expression/expressions.go
+++ b/expression/expressions.go
@@ -1,4 +1,6 @@
-// Package expression parses and evaluates the expression language that is used in objects {{a.b[c]}} and tag parameters {%assign pages = site.pages | reverse%}.
+// Package expression parses and evaluates the expression language.
+//
+// This is the language that is used inside Liquid object and tags; e.g. "a.b[c]" in {{ a.b[c] }}, and "pages = site.pages | reverse" in {% assign pages = site.pages | reverse %}.
 package expression
 
 import (
diff --git a/parser/parser.go b/parser/parser.go
index b0feb79..6de9b56 100644
--- a/parser/parser.go
+++ b/parser/parser.go
@@ -1,9 +1,4 @@
-// Package parser parses template source into a render tree, which can be applied
-// to variable bindings to produce output.
-//
-// Except where noted in the documentation for the liquid package, even public symbols
-// in this package are intended to be public only to other subpackages within this
-// repo, and are not guaranteed stable even across subminor version number increments.
+// Package parser parses template source into an abstract syntax tree.
 package parser
 
 import (