From 5afdd4754470afbf979ebc6c8575b37df0e8c44e Mon Sep 17 00:00:00 2001
From: sauerbraten <willing.alexander@googlemail.com>
Date: Thu, 9 Jul 2020 13:29:32 +0200
Subject: [PATCH] update docs on SafeWriter and Renderer built-ins

---
 default.go       |  4 ++--
 docs/builtins.md | 33 ++++++++++++++++++++++++++++++++-
 eval.go          |  6 +++---
 3 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/default.go b/default.go
index c01f89a..a805242 100644
--- a/default.go
+++ b/default.go
@@ -170,8 +170,8 @@ func unsafePrinter(w io.Writer, b []byte) {
 	w.Write(b)
 }
 
-// SafeWriter escapee func. Functions implementing this type will write directly into the writer,
-// skipping the escape phase; use this type to create special types of escapee funcs.
+// SafeWriter is a function that writes bytes directly to the render output, without going through Jet's auto-escaping phase.
+// Use/implement this if content should be escaped differently or not at all (see raw/unsafe builtins).
 type SafeWriter func(io.Writer, []byte)
 
 var stringType = reflect.TypeOf("")
diff --git a/docs/builtins.md b/docs/builtins.md
index 404dc6c..6a8883b 100644
--- a/docs/builtins.md
+++ b/docs/builtins.md
@@ -6,6 +6,12 @@
   - [isset](#isset)
   - [exec](#exec)
   - [ints](#ints)
+- [SafeWriter](#safewriter)
+  - [safeHtml](#safehtml)
+  - [safeJs](#safejs)
+  - [raw/unsafe](#rawunsafe)
+- [Renderer](#renderer)
+    - [writeJson](#writejson)
 
 ## Functions
 
@@ -23,6 +29,7 @@ The following functions simply expose functions from Go's standard library for c
 - `trimSpace`: exposes Go's [strings.TrimSpace](https://golang.org/pkg/strings/#TrimSpace)
 - `html`: exposes Go's [html.EscapeString](https://golang.org/pkg/html/#EscapeString)
 - `url`: exposes Go's [url.QueryEscape](https://golang.org/pkg/net/url/#QueryEscape)
+- `json`: exposes Go's [json.Marshal](https://golang.org/pkg/encoding/json/#Marshal)
 
 ### len
 
@@ -42,4 +49,28 @@ It panics if you pass a value of any type other than string, array, slice, map,
 
 ### ints
 
-`ints()` takes two integers as lower and upper limit and returns a Ranger producing all the integers between them, including the lower and excluding the upper limit. It panics when the arguments can't be converted to integers or when the upper limit is not strictly greater than the lower limit.
\ No newline at end of file
+`ints()` takes two integers as lower and upper limit and returns a Ranger producing all the integers between them, including the lower and excluding the upper limit. It panics when the arguments can't be converted to integers or when the upper limit is not strictly greater than the lower limit.
+
+## SafeWriter
+
+Jet includes a [`SafeWriter`](https://pkg.go.dev/github.com/CloudyKit/jet/v4@v4.0.1?tab=doc#SafeWriter) function type for writing directly to the render output stream. This can be used to circumvent Jet's default HTML escaping. Jet has a few such functions built-in.
+
+### safeHtml
+
+`safeHtml` is an alias for Go's [template.HTMLEscape](https://golang.org/pkg/text/template/#HTMLEscape) (converted to the `SafeWriter` type). This is the same escape function that's also applied to the evalutation result of action nodes by default. It escapes everything that could be interpreted as HTML.
+
+### safeJs
+
+`safeJs` is an alias for Go's [template.JSEscape](https://golang.org/pkg/text/template/#JSEscape). It escapes data to be safe to use in a Javascript context.
+
+### raw/unsafe
+
+`raw` (alias `unsafe`) is a writer that escapes nothing at all, allowing you to circumvent Jet's default HTML escaping. Use with caution!
+
+## Renderer
+
+Jet exports a [`Renderer`](https://pkg.go.dev/github.com/CloudyKit/jet/v4@v4.0.1?tab=doc#Renderer) interface (and [`RendererFunc`](https://pkg.go.dev/github.com/CloudyKit/jet/v4@v4.0.1?tab=doc#RendererFunc) type which implements the interface). When an action evaluates to a value implementinng this interface, it will not be rendered using [fastprinter](https://github.com/CloudyKit/fastprinter), but by calling its Render() function instead.
+
+#### writeJson
+
+`writeJson` renders the JSON encoding of whatever you pass in to the output, escaping only "<", ">", and "&" (just like the `json` function).
\ No newline at end of file
diff --git a/eval.go b/eval.go
index 13cc111..51d874c 100644
--- a/eval.go
+++ b/eval.go
@@ -41,9 +41,9 @@ var (
 	}
 )
 
-// Renderer any resulting value from an expression in an action that implements this
-// interface will not be printed, instead, we will invoke his Render() method which will be responsible
-// to render his self
+// Renderer is used to detect if a value has its own rendering logic. If the value an action evaluates to implements this
+// interface, it will not be printed using github.com/CloudyKit/fastprinter, instead, its Render() method will be called
+// and is responsible for writing the value to the render output.
 type Renderer interface {
 	Render(*Runtime)
 }