chore(docs): improved render of the docs for 'template' (#471)

lua/pl/template.lua

@@ -103,20 +103,21 @@ local template = {}
 --- expand the template using the specified environment.
 -- This function will compile and render the template. For more performant
 -- recurring usage use the two step approach by using `compile` and `ct:render`.
--- There are six special fields in the environment table `env`
---
---   * `_parent`: continue looking up in this table (e.g. `_parent=_G`).
---   * `_brackets`: bracket pair that wraps inline Lua expressions,  default is '()'.
---   * `_escape`: character marking Lua lines, default is '#'
---   * `_inline_escape`: character marking inline Lua expression, default is '$'.
---   * `_chunk_name`: chunk name for loaded templates, used if there
---     is an error in Lua code. Default is 'TMP'.
---   * `_debug`: if truthy, the generated code will be printed upon a render error
---
 -- @string str the template string
--- @tab[opt] env the environment
--- @return `rendered template + nil + source_code`, or `nil + error + source_code`. The last
--- return value (`source_code`) is only returned if the debug option is used.
+-- @tparam[opt] table env the environment. This table has the following special fields:
+-- @tparam[opt=nil] table env._parent continue looking up in this table (e.g. `_parent=_G`).
+-- @tparam[opt="()"] string env._brackets bracket pair that wraps inline Lua expressions.
+-- @tparam[opt="#"] string env._escape character marking Lua lines.
+-- @tparam[opt="$"] string env._inline_escape character marking inline Lua expression.
+-- @tparam[opt="TMP"] string env._chunk_name chunk name for loaded templates, used if there
+-- is an error in Lua code.
+-- @tparam[opt=false] boolean env._debug if truthy, the generated code will be printed upon a render error.
+-- @treturn[1] string render result
+-- @treturn[1] nil
+-- @treturn[1] string source_code (only if '`env._debug`' was truthy).
+-- @treturn[2] nil
+-- @treturn[2] string error message
+-- @treturn[2] string source_code (only if '`env._debug`' was truthy).
 function template.substitute(str, env)
     env = env or {}
     local t, err = template.compile(str, {
@@ -138,8 +139,12 @@ end
 -- @tab[opt] parent continue looking up in this table (e.g. `parent=_G`).
 -- @bool[opt] db if thruthy, it will print the code upon a render error
 -- (provided the template was compiled with the debug option).
--- @return `rendered template + nil + source_code`, or `nil + error + source_code`. The last return value
--- (`source_code`) is only returned if the template was compiled with the debug option.
+-- @treturn[1] string render result
+-- @treturn[1] nil
+-- @treturn[1] string source_code (only if '`env._debug`' was truthy).
+-- @treturn[2] nil
+-- @treturn[2] string error message
+-- @treturn[2] string source_code (only if '`env._debug`' was truthy).
 -- @usage
 -- local ct, err = template.compile(my_template)
 -- local rendered , err = ct:render(my_env, parent)
@@ -162,19 +167,20 @@ end
 -- Returns an object that can repeatedly be rendered without parsing/compiling
 -- the template again. Preserves the line layout of the template so that line
 -- numbers in error messages should point to the correct lines in the source
--- string. The options passed in the `opts` table support the following options:
---
---   * `chunk_name`: chunk name for loaded templates, used if there
---     is an error in Lua code. Default is 'TMP'.
---   * `escape`: character marking Lua lines, default is '#'
---   * `inline_escape`: character marking inline Lua expression, default is '$'.
---   * `inline_brackets`: bracket pair that wraps inline Lua expressions, default is '()'.
---   * `newline`: if truthy, newlines will be stripped from text in the template. Default is `false`.
---   * `debug`: if truthy, the generated source code will be retained within the compiled template object, default is `nil`.
---
--- @string str the template string
--- @tab[opt] opts the compilation options to use
--- @return template object, or `nil + error + source_code`
+-- string.
+-- @tparam string str the template string
+-- @tparam[opt] table opts the compilation options to use. This table supports the following options:
+-- @tparam[opt="TMP"] string opts.chunk_name chunk name for loaded templates, used if there
+-- is an error in Lua code.
+-- @tparam[opt="#"] string opts.escape character marking Lua lines.
+-- @tparam[opt="$"] string opts.inline_escape character marking inline Lua expression.
+-- @tparam[opt="()"] string opts.inline_brackets bracket pair that wraps inline Lua expressions.
+-- @tparam[opt=false] boolean opts.newline if truthy, newlines will be stripped from text in the template.
+-- @tparam[opt=false] boolean opts.debug if truthy, the generated code will be printed upon a render error.
+-- @treturn[1] ct compiled template object
+-- @treturn[2] nil
+-- @treturn[2] string error message
+-- @treturn[2] string source_code
 -- @usage
 -- local ct, err = template.compile(my_template)
 -- local rendered , err = ct:render(my_env, parent)