Clarify data type returned by partial and partialCached

content/en/functions/go-template/_index.md

@@ -1,14 +1,14 @@
 ---
-title: Go template functions
+title: Go template functions, operators, and statements
 linkTitle: go template
-description: Template functions and statements provided by Go's text/template package.
+description: Template functions, operators, and statements provided by Go's text/template package.
 categories: []
 keywords: []
 menu:
   docs:
     parent: functions
 ---
 
-These are the statements, operators, and functions provided by Go's [text/template] package.
+These are the functions, operators, and statements provided by Go's [text/template] package.
 
 [text/template]: https://pkg.go.dev/text/template

content/en/functions/go-template/return.md

@@ -0,0 +1,110 @@
+---
+title: return
+description: Used within partial templates, terminates template execution and returns the given value, if any.
+categories: []
+keywords: []
+action:
+  aliases: []
+  related:
+    - functions/partials/Include
+    - functions/partials/IncludeCached
+  returnType: any
+  signatures: ['return [VALUE]']
+toc: true
+---
+
+The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
+
+The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`].
+
+A `return` statement without a value returns an empty string of type `template.HTML`.
+
+[`bool`]: /getting-started/glossary/#bool
+[`float`]: /getting-started/glossary/#float
+[`int`]: /getting-started/glossary/#int
+[`map`]: /getting-started/glossary/#map
+[`resource`]: /getting-started/glossary/#resource
+[`slice`]: /getting-started/glossary/#slice
+[`string`]: /getting-started/glossary/#string
+[text/template]: https://pkg.go.dev/text/template
+
+{{% note %}}
+Unlike `return` statements in other languages, Hugo executes the first occurence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
+{{% /note %}}
+
+## Example
+
+By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even:
+
+{{< code file="layouts/partials/odd-or-even.html" >}}
+{{ if math.ModBool . 2 }}
+  <p>{{ . }} is even</p>
+{{ else }}
+  <p>{{ . }} is odd</p>
+{{ end }}
+{{< /code >}}
+
+When called, the partial renders HTML:
+
+```go-html-template
+{{ partial "odd-or-even.html" 42 }} → <p>42 is even</p>
+```
+
+Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even:
+
+{{< code file="layouts/partials/is-even.html" >}}
+{{ return math.ModBool . 2 }}
+{{< /code >}}
+
+With this template:
+
+```go-html-template
+{{ $number := 42 }}
+{{ if partial "is-even.html" $number }}
+  <p>{{ $number }} is even</p>
+{{ else }}
+  <p>{{ $number }} is odd</p>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<p>42 is even</p>
+```
+
+See additional examples in the [partial templates] section.
+
+[partial templates]: /templates/partials/#returning-a-value-from-a-partial
+
+## Usage
+
+{{% note %}}
+Unlike `return` statements in other languages, Hugo executes the first occurence of the `return` statement regardless of its position within logical blocks
+{{% /note %}}
+
+A partial that returns a value must contain only one `return` statement, placed at the end of the template.
+
+For example:
+
+{{< code file="layouts/partials/is-even.html" >}}
+{{ $result := false }}
+{{ if math.ModBool . 2 }}
+  {{ $result = "even" }}
+{{ else }}
+  {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+{{< /code >}}
+
+{{% note %}}
+The construct below is incorrect; it contains more than one `return` statement.
+{{% /note %}}
+
+{{< code file="layouts/partials/do-not-do-this.html" >}}
+{{ if math.ModBool . 2 }}
+  {{ return "even" }}
+{{ else }}
+  {{ return "odd" }}
+{{ end }}
+{{< /code >}}

content/en/functions/partials/Include.md

@@ -1,19 +1,24 @@
 ---
 title: partials.Include
-description: Executes the given partial template, optionally passing context. If the partial contains a return statement, returns that value, else returns the rendered output.
+description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
 categories: []
 keywords: []
 action:
   aliases: [partial]
   related:
-    - functions/go-template/template
+    - functions/go-template/return
     - functions/partials/IncludeCached
+    - functions/go-template/template
     - methods/page/Render
   returnType: any
   signatures: ['partials.Include NAME [CONTEXT]']
 aliases: [/functions/partial]
 ---
 
+Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type.
+
+[`return`]: /functions/go-template/return
+
 In this example we have three partial templates:
 
 ```text
@@ -60,4 +65,21 @@ Then, within the partial template:
 <p>{{ .name }} is majoring in {{ .major }}. Their grade point average is {{ .gpa }}.</p>
 ```
 
+To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
+
+```go-html-template
+{{ $result := false }}
+{{ if math.ModBool . 2 }}
+  {{ $result = "even" }}
+{{ else }}
+  {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+See&nbsp;[details][`return`].
+
+[`return`]: /functions/go-template/return
+
 [breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants
+[details]: /functions/go-template/return

content/en/functions/partials/IncludeCached.md

@@ -1,13 +1,14 @@
 ---
 title: partials.IncludeCached
-description: Executes the given template and caches the result, optionally passing context. If the partial contains a return statement, returns that value, else returns the rendered output.
+description: Executes the given template and caches the result, optionally passing context. If the partial template contains a return statement, returns teh given value, else returns the rendered output.
 categories: []
 keywords: []
 action:
   aliases: [partialCached]
   related:
-    - functions/go-template/template
+    - functions/go-template/return
     - functions/partials/Include
+    - functions/go-template/template
     - methods/page/Render
   returnType: any
   signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]']
@@ -17,7 +18,11 @@ signatures:
 aliases: [/functions/partialcached]
 ---
 
-The `partialCached` template function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
+Without a [`return`] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type.
+
+
+
+The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
 
 {{% note %}}
 Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once.
@@ -31,18 +36,32 @@ Here is the simplest usage:
 {{ partialCached "footer.html" . }}
 ```
 
-You can also pass additional arguments to `partialCached` to create *variants* of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, you could use a variant based upon section so that the partial is only rendered once per section:
+Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section:
 
 {{< code file=partial-cached-example.html >}}
 {{ partialCached "footer.html" . .Section }}
 {{< /code >}}
 
-If you need to pass additional arguments to create unique variants, you can pass as many variant arguments as you need:
+Pass additional arguments, of any data type, as needed to create unique variants:
 
 ```go-html-template
 {{ partialCached "footer.html" . .Params.country .Params.province }}
 ```
 
-Note that the variant arguments are not made available to the underlying partial template. They are only use to create a unique cache key. Since Hugo `0.61.0` you can use any object as cache key(s), not just strings.
+The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. 
+
+To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template:
+
+```go-html-template
+{{ $result := false }}
+{{ if math.ModBool . 2 }}
+  {{ $result = "even" }}
+{{ else }}
+  {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+See&nbsp;[details][`return`].
 
-See also [The Full Partial Series Part 1: Caching!](https://regisphilibert.com/blog/2019/12/hugo-partial-series-part-1-caching-with-partialcached/).
+[`return`]: /functions/go-template/return