docs: automatic generate PDK docs by LDoc (#6321)

.licenserc.yaml

@@ -42,5 +42,6 @@ header:
     # Exclude plugin-specific configuration files
     - 't/plugin/authz-casbin'
     - 't/coredns'
+    - 'autodocs/'
 
   comment: on-failure

apisix/core/config_etcd.lua

@@ -15,6 +15,10 @@
 -- limitations under the License.
 --
 
+--- Get configuration information.
+--
+-- @module core.config_etcd
+
 local table        = require("apisix.core.table")
 local config_local = require("apisix.core.config_local")
 local log          = require("apisix.core.log")
@@ -604,6 +608,28 @@ local function _automatic_fetch(premature, self)
 end
 
 
+---
+-- Create a new connection to communicate with the control plane.
+-- This function should be used in the `init_worker_by_lua` phase.
+--
+-- @function core.config.new
+-- @tparam string etcd directory to be monitored, e.g. "/routes".
+-- @tparam table opts Parameters related to the etcd client connection.
+-- The keys in `opts` are as follows:
+--  * automatic: whether to get the latest etcd data automatically
+--  * item_schema: the jsonschema that checks the value of each item under the **key** directory
+--  * filter: the custom function to filter the value of each item under the **key** directory
+--  * timeout: the timeout for watch operation, default is 30s
+--  * single_item: whether only one item under the **key** directory
+--  * checker: the custom function to check the value of each item under the **key** directory
+-- @treturn table The etcd client connection.
+-- @usage
+-- local plugins_conf, err = core.config.new("/custom_dir", {
+--    automatic = true,
+--    filter = function(item)
+--        -- called once before reload for sync data from admin
+--    end,
+--})
 function _M.new(key, opts)
     local local_conf, err = config_local.local_conf()
     if not local_conf then

apisix/core/config_local.lua

@@ -15,6 +15,10 @@
 -- limitations under the License.
 --
 
+--- Get configuration information.
+--
+-- @module core.config_local
+
 local file = require("apisix.cli.file")
 local schema = require("apisix.cli.schema")
 
@@ -29,7 +33,27 @@ function _M.clear_cache()
     config_data = nil
 end
 
-
+---
+-- Get the local config info.
+-- The configuration information consists of two parts, user-defined configuration in
+-- `conf/config.yaml` and default configuration in `conf/config-default.yaml`. The configuration
+-- of the same name present in `conf/config.yaml` will overwrite `conf/config-default.yaml`.
+-- The final full configuration is `conf/config.yaml` and the default configuration in
+-- `conf/config-default.yaml` that is not overwritten.
+--
+-- @function core.config_local.local_conf
+-- @treturn table The configuration information.
+-- @usage
+-- -- Given a config item in `conf/config.yaml`:
+-- --
+-- -- apisix:
+-- --   ssl:
+-- --     fallback_sni: "a.test2.com"
+-- --
+-- -- you can get the value of `fallback_sni` by:
+-- local local_conf = core.config.local_conf()
+-- local fallback_sni = core.table.try_read_attr(
+--                        local_conf, "apisix", "ssl", "fallback_sni") -- "a.test2.com"
 function _M.local_conf(force)
     if not force and config_data then
         return config_data

apisix/core/config_util.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Collection of util functions
+--
+-- @module core.config_util
+
 local core_tab = require("apisix.core.table")
 local str_byte = string.byte
 local str_char = string.char
@@ -68,6 +73,8 @@ function _M.cancel_clean_handler(item, idx, fire)
 end
 
 
+---
+-- Convert different time units to seconds as time units.
 -- Time intervals can be specified in milliseconds, seconds, minutes, hours, days and so on,
 -- using the following suffixes:
 -- ms	milliseconds
@@ -81,6 +88,12 @@ end
 -- Multiple units can be combined in a single value by specifying them in the order from the most
 -- to the least significant, and optionally separated by whitespace.
 -- A value without a suffix means seconds.
+--
+-- @function core.config_util.parse_time_unit
+-- @tparam number|string Strings with time units, e.g. "60m".
+-- @treturn number Number of seconds after conversion
+-- @usage
+-- local seconds = core.config_util.parse_time_unit("60m") -- 3600
 function _M.parse_time_unit(s)
     local typ = type(s)
     if typ == "number" then

apisix/core/config_yaml.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Get configuration information in Stand-alone mode.
+--
+-- @module core.config_yaml
+
 local config_local = require("apisix.core.config_local")
 local yaml         = require("tinyyaml")
 local log          = require("apisix.core.log")

apisix/core/ctx.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Define the request context.
+--
+-- @module core.ctx
+
 local core_str     = require("apisix.core.string")
 local core_tab     = require("apisix.core.table")
 local request      = require("apisix.core.request")
@@ -301,6 +306,25 @@ do
         end,
     }
 
+---
+-- Register custom variables.
+-- Register variables globally, and use them as normal builtin variables.
+-- Note that the custom variables can't be used in features that depend
+-- on the Nginx directive, like `access_log_format`.
+--
+-- @function core.ctx.register_var
+-- @tparam string name custom variable name
+-- @tparam function getter The fetch function for custom variables.
+-- @usage
+-- local core = require "apisix.core"
+--
+-- core.ctx.register_var("a6_labels_zone", function(ctx)
+--     local route = ctx.matched_route and ctx.matched_route.value
+--     if route and route.labels then
+--         return route.labels.zone
+--     end
+--     return nil
+-- end)
 function _M.register_var(name, getter)
     if type(getter) ~= "function" then
         error("the getter of registered var should be a function")

apisix/core/dns/client.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Wrapped dns search client.
+--
+-- @module core.dns.client
+
 local require = require
 local config_local = require("apisix.core.config_local")
 local log = require("apisix.core.log")

apisix/core/etcd.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Etcd API.
+--
+-- @module core.etcd
+
 local fetch_local_conf = require("apisix.core.config_local").local_conf
 local array_mt         = require("apisix.core.json").array_mt
 local etcd             = require("resty.etcd")
@@ -364,7 +369,18 @@ function _M.delete(key)
     return res, nil
 end
 
-
+---
+-- Get etcd cluster and server version.
+--
+-- @function core.etcd.server_version
+-- @treturn table The response of query etcd server version.
+-- @usage
+-- local res, err = core.etcd.server_version()
+-- -- the res.body is as follows:
+-- -- {
+-- --   etcdcluster = "3.5.0",
+-- --   etcdserver = "3.5.0"
+-- -- }
 function _M.server_version()
     local etcd_cli, err = new()
     if not etcd_cli then

apisix/core/id.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Instance id of APISIX
+--
+-- @module core.id
+
 local fetch_local_conf = require("apisix.core.config_local").local_conf
 local try_read_attr    = require("apisix.core.table").try_read_attr
 local log              = require("apisix.core.log")
@@ -84,7 +89,13 @@ function _M.init()
     end
 end
 
-
+---
+-- Returns the instance id of the running APISIX
+--
+-- @function core.id.get
+-- @treturn string the instance id
+-- @usage
+-- local apisix_id = core.id.get()
 function _M.get()
     return apisix_uid
 end

apisix/core/io.lua

@@ -15,12 +15,26 @@
 -- limitations under the License.
 --
 
+--- I/O operations on files.
+--
+-- @module core.io
+
 local open = io.open
 
 
 local _M = {}
 
-
+---
+-- Read the contents of a file.
+--
+-- @function core.io.get_file
+-- @tparam string file_name either an absolute path or
+-- a relative path based on the APISIX working directory.
+-- @treturn string The file content.
+-- @usage
+-- local file_content, err = core.io.get_file("conf/apisix.uid")
+-- -- the `file_content` maybe the APISIX instance id in uuid format,
+-- -- like "3f0e827b-5f26-440e-8074-c101c8eb0174"
 function _M.get_file(file_name)
     local f, err = open(file_name, 'r')
     if not f then

apisix/core/ip.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- IP match and verify module.
+--
+-- @module core.ip
+
 local json = require("apisix.core.json")
 local log = require("apisix.core.log")
 local ipmatcher = require("resty.ipmatcher")
@@ -36,7 +41,16 @@ function _M.create_ip_matcher(ip_list)
     return ip
 end
 
-
+---
+-- Verify that the given ip is a valid ip or cidr.
+--
+-- @function core.ip.validate_cidr_or_ip
+-- @tparam string ip IP or cidr.
+-- @treturn boolean True if the given ip is a valid ip or cidr, false otherwise.
+-- @usage
+-- local ip1 = core.ip.validate_cidr_or_ip("127.0.0.1") -- true
+-- local cidr = core.ip.validate_cidr_or_ip("113.74.26.106/24") -- true
+-- local ip2 = core.ip.validate_cidr_or_ip("113.74.26.666") -- false
 function _M.validate_cidr_or_ip(ip)
     local mask = 0
     local sep_pos = str_find(ip, "/")

apisix/core/json.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Wrapped serialization and deserialization modules for json and lua tables.
+--
+-- @module core.json
+
 local cjson = require("cjson.safe")
 local json_encode = cjson.encode
 local clear_tab = require("table.clear")
@@ -95,8 +100,18 @@ local delay_tab = setmetatable({data = "", force = false}, {
 })
 
 
--- this is a non-thread safe implementation
--- it works well with log, eg: log.info(..., json.delay_encode({...}))
+---
+-- Delayed encoding of input data, avoid unnecessary encode operations.
+-- When really writing logs, if the given parameter is table, it will be converted to string in
+-- OpenResty by checking if there is a metamethod registered for `__tostring`, and if so,
+-- calling this method to convert it to string.
+--
+-- @function core.json.delay_encode
+-- @tparam string|table data The data to be encoded.
+-- @tparam boolean force Whether to clear the log buffer.
+-- @treturn table The table with the __tostring function overridden.
+-- @usage
+-- core.log.info("conf  : ", core.json.delay_encode(conf))
 function _M.delay_encode(data, force)
     delay_tab.data = data
     delay_tab.force = force

apisix/core/log.lua

@@ -15,6 +15,10 @@
 -- limitations under the License.
 --
 
+--- Wrapped `ngx.log`.
+--
+-- @module core.log
+
 local ngx = ngx
 local ngx_log  = ngx.log
 local require  = require
@@ -139,8 +143,20 @@ local delay_tab = setmetatable({
 })
 
 
+---
+-- Delayed execute log printing.
 -- It works well with log.$level, eg: log.info(..., log.delay_exec(func, ...))
 -- Should not use it elsewhere.
+--
+-- @function core.log.delay_exec
+-- @tparam function func Functions that need to be delayed during log printing.
+-- @treturn table The table with the res attribute overridden.
+-- @usage
+-- local function delay_func(param1, param2)
+--     return param1 .. " " .. param2
+-- end
+-- core.log.info("delay log print: ", core.log.delay_exec(delay_func, "hello", "world))
+-- -- then the log will be: "delay log print: hello world"
 function _M.delay_exec(func, ...)
     delay_tab.func = func
 

apisix/core/lrucache.lua

@@ -15,6 +15,10 @@
 -- limitations under the License.
 --
 
+--- LRU Caching Implementation.
+--
+-- @module core.lrucache
+
 local lru_new = require("resty.lrucache").new
 local resty_lock = require("resty.lock")
 local log = require("apisix.core.log")
@@ -148,6 +152,24 @@ local function plugin_ctx_key_and_ver(api_ctx, extra_key)
     return key, api_ctx.conf_version
 end
 
+---
+--  Cache some objects for plugins to avoid duplicate resources creation.
+--
+-- @function core.lrucache.plugin_ctx
+-- @tparam table lrucache LRUCache object instance.
+-- @tparam table api_ctx The request context.
+-- @tparam string extra_key Additional parameters for generating the lrucache identification key.
+-- @tparam function create_obj_func Functions for creating cache objects.
+-- If the object does not exist in the lrucache, this function is
+-- called to create it and cache it in the lrucache.
+-- @treturn table The object cached in lrucache.
+-- @usage
+-- local function create_obj() {
+-- --   create the object
+-- --   return the object
+-- }
+-- local obj, err = core.lrucache.plugin_ctx(lrucache, ctx, nil, create_obj)
+-- -- obj is the object cached in lrucache
 local function plugin_ctx(lrucache, api_ctx, extra_key, create_obj_func, ...)
     local key, ver = plugin_ctx_key_and_ver(api_ctx, extra_key)
     return lrucache(key, ver, create_obj_func, ...)

apisix/core/os.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- OS module.
+--
+-- @module core.os
+
 local ffi = require("ffi")
 local ffi_str = ffi.string
 local ffi_errno = ffi.errno
@@ -42,8 +47,15 @@ local function err()
     return ffi_str(C.strerror(ffi_errno()))
 end
 
-
--- setenv sets the value of the environment variable
+---
+--  Sets the value of the environment variable.
+--
+-- @function core.os.setenv
+-- @tparam string name The name of environment variable.
+-- @tparam string value The value of environment variable.
+-- @treturn boolean Results of setting environment variables, true on success.
+-- @usage
+-- local ok, err = core.os.setenv("foo", "bar")
 function _M.setenv(name, value)
     local tv = type(value)
     if type(name) ~= "string" or (tv ~= "string" and tv ~= "number") then

apisix/core/profile.lua

@@ -15,13 +15,29 @@
 -- limitations under the License.
 --
 
+--- Profile module.
+--
+-- @module core.profile
+
 local _M = {
     version = 0.1,
     profile = os.getenv("APISIX_PROFILE"),
     apisix_home = (ngx and ngx.config.prefix()) or ""
 }
 
-
+---
+--  Get yaml file path by filename under the `conf/`.
+--
+-- @function core.profile.yaml_path
+-- @tparam self self The profile module itself.
+-- @tparam string file_name Name of the yaml file to search.
+-- @treturn string The path of yaml file searched.
+-- @usage
+-- local profile = require("apisix.core.profile")
+-- ......
+-- -- set the working directory of APISIX
+-- profile.apisix_home = env.apisix_home .. "/"
+-- local local_conf_path = profile:yaml_path("config")
 function _M.yaml_path(self, file_name)
     local file_path = self.apisix_home  .. "conf/" .. file_name
     if self.profile and file_name ~= "config-default" then

apisix/core/request.lua

@@ -15,6 +15,10 @@
 -- limitations under the License.
 --
 
+--- Get or set the information of the client request.
+--
+-- @module core.request
+
 local lfs = require("lfs")
 local log = require("apisix.core.log")
 local io = require("apisix.core.io")
@@ -60,9 +64,27 @@ local function _validate_header_name(name)
     return name
 end
 
+---
+-- Returns all headers of the current request.
+-- The name and value of the header in return table is in lower case.
+--
+-- @function core.request.headers
+-- @tparam table ctx The context of the current request.
+-- @treturn table all headers
+-- @usage
+-- local headers = core.request.headers(ctx)
 _M.headers = _headers
 
-
+---
+-- Returns the value of the header with the specified name.
+--
+-- @function core.request.header
+-- @tparam table ctx The context of the current request.
+-- @tparam string name The header name, example: "Content-Type".
+-- @treturn string|nil the value of the header, or nil if not found.
+-- @usage
+-- -- You can use upper case for header "Content-Type" here to get the value.
+-- local content_type = core.request.header(ctx, "Content-Type") -- "application/json"
 function _M.header(ctx, name)
     if not ctx then
         ctx = ngx.ctx.api_ctx

apisix/core/resolver.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Domain Resolver.
+--
+-- @module core.resolver
+
 local json = require("apisix.core.json")
 local log = require("apisix.core.log")
 local utils = require("apisix.core.utils")
@@ -28,7 +33,14 @@ function _M.init_resolver(args)
     log.info("dns resolver ", json.delay_encode(dns_resolver, true))
 end
 
-
+---
+--  Resolve domain name to ip.
+--
+-- @function core.resolver.parse_domain
+-- @tparam string host Domain name that need to be resolved.
+-- @treturn string The IP of the domain name after being resolved.
+-- @usage
+-- local ip, err = core.resolver.parse_domain("apache.org") -- "198.18.10.114"
 function _M.parse_domain(host)
     local ip_info, err = utils.dns_parse(host)
     if not ip_info then

apisix/core/response.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Get the information form upstream response, or set the information to client response.
+--
+-- @module core.response
+
 local encode_json = require("cjson.safe").encode
 local ngx = ngx
 local arg = ngx.arg
@@ -131,7 +136,12 @@ function _M.set_header(...)
     set_header(false, ...)
 end
 
-
+---
+-- Add a header to the client response.
+--
+-- @function core.response.add_header
+-- @usage
+-- core.response.add_header("Apisix-Plugins", "no plugin")
 function _M.add_header(...)
     set_header(true, ...)
 end

apisix/core/schema.lua

@@ -15,6 +15,10 @@
 -- limitations under the License.
 --
 
+--- Json schema validation module.
+--
+-- @module core.schema
+
 local jsonschema = require('jsonschema')
 local lrucache = require("apisix.core.lrucache")
 local cached_validator = lrucache.new({count = 1000, ttl = 0})

apisix/core/string.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Wrapped string module.
+--
+-- @module core.string
+
 local error = error
 local type = type
 local str_byte = string.byte
@@ -43,7 +48,15 @@ function _M.find(haystack, needle, from)
     return str_find(haystack, needle, from or 1, true)
 end
 
-
+---
+--  Tests whether the string s begins with prefix.
+--
+-- @function core.string.has_prefix
+-- @tparam string s The string being tested.
+-- @tparam string prefix Specify the prefix.
+-- @treturn boolean Test result, true means the string s begins with prefix.
+-- @usage
+-- local res = core.string.has_prefix("/apisix/admin/routes", "/apisix/") -- true
 function _M.has_prefix(s, prefix)
     if type(s) ~= "string" or type(prefix) ~= "string" then
         error("unexpected type: s:" .. type(s) .. ", prefix:" .. type(prefix))

apisix/core/table.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Wrapped table module.
+--
+-- @module core.table
+
 local newproxy     = newproxy
 local getmetatable = getmetatable
 local setmetatable = setmetatable
@@ -75,7 +80,16 @@ function _M.try_read_attr(tab, ...)
     return tab
 end
 
-
+---
+--  Test if an element exists in an array.
+--
+-- @function core.table.array_find
+-- @tparam table array The tested array.
+-- @tparam string val The tested value.
+-- @treturn number The index of tested value.
+-- @usage
+-- local arr = {"a", "b", "c"}
+-- local idx = core.table.array_find(arr, "b") -- idx = 2
 function _M.array_find(array, val)
     for i, v in ipairs(array) do
         if v == val then

apisix/core/timer.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Wrapped timer module, can cancel the running timers.
+--
+-- @module core.timer
+
 local log = require("apisix.core.log")
 local sleep = require("apisix.core.utils").sleep
 local timer_every = ngx.timer.every

apisix/core/utils.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Collection of util functions.
+--
+-- @module core.utils
+
 local config_local   = require("apisix.core.config_local")
 local core_str       = require("apisix.core.string")
 local rfind_char     = core_str.rfind_char
@@ -235,7 +240,14 @@ function _M.validate_header_value(value)
 end
 
 
+---
+-- Returns the standard host name of the local host.
 -- only use this method in init/init_worker phase.
+--
+-- @function core.utils.gethostname
+-- @treturn string The host name of the local host.
+-- @usage
+-- local hostname = core.utils.gethostname() -- "localhost"
 function _M.gethostname()
     if hostname then
         return hostname

apisix/core/vault.lua

@@ -15,6 +15,11 @@
 -- limitations under the License.
 --
 
+--- Vault Tools.
+--  Vault is an identity-based secrets and encryption management system.
+--
+-- @module core.vault
+
 local core = require("apisix.core")
 local http = require("resty.http")
 local json = require("cjson")

apisix/core/version.lua

@@ -14,6 +14,11 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
+
+--- Return APISIX current version.
+--
+-- @module core.version
+
 return {
     VERSION = "2.12.0"
 }

autodocs/config.ld

@@ -0,0 +1,11 @@
+project='Apache APISIX'
+title='Plugin Develop Docs'
+description='Functions in APISIX core'
+format='markdown'
+backtick_references = false
+no_lua_ref = true
+all = false
+no_space_before_args = true
+ext = "md"
+template = true -- use the ldoc.ltp as markdown template
+template_escape = ">"

autodocs/generate.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+set -ex
+
+# workdir is the root of the apisix, use command: autodocs/generate.sh build to generate the docs,
+# and the output will be in the workdir/autodocs/output/ directory.
+build() {
+    # install dependencies
+    apt-get -y update --fix-missing
+    apt-get -y install lua5.1 liblua5.1-0-dev
+    curl https://raw.githubusercontent.com/apache/apisix/master/utils/linux-install-luarocks.sh -sL | bash -
+    luarocks install ldoc
+
+    # generate docs
+    rm -rf autodocs/output || true
+    mkdir autodocs/output || true
+    cd autodocs/output
+    find ../../apisix/core -name "*.lua" -type f -exec ldoc -c ../config.ld {} \;
+
+    # generate the markdown files' name
+    rm ../md_files_name.txt || true
+    output="./"
+    mds=$(ls $output)
+    for md in $mds
+    do
+       echo $md >> ../md_files_name.txt
+    done
+}
+
+case_opt=$1
+case $case_opt in
+    (build)
+        build
+        ;;
+esac

autodocs/ldoc.ltp

@@ -0,0 +1,98 @@
+> local iter = ldoc.modules.iter
+> local display_name = ldoc.display_name
+> local function trim_newline(s)
+>   return (s:gsub("\n", "\r"))
+> end
+---
+title: APISIX Plugin Development Docs
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## $(ldoc.title)
+
+### $(module.name)
+
+$(module.summary) $(module.description)
+>
+> for kind, items in module.kinds() do
+>    for item in items() do
+
+#### $(trim_newline(display_name(item)))
+>       if item.type == "function" then
+>          if item.summary and item.summary ~= '' then
+
+**Summary**: $(item.summary)
+>          end -- if item.summary
+>          if item.description and item.description ~= '' then
+
+**Description**:
+
+```text$(trim_newline(item.description))
+```
+>          end -- if item.description
+>       end -- if item.type
+>       if item.params and #item.params > 0 then
+>          local subnames = module.kinds:type_of(item).subnames
+>          if subnames then
+
+**$(subnames)**
+
+>          end -- if subnames
+>          -- print the parameters
+>          for par in iter(item.params) do
+>             local param = item:subparam(par)
+>             for p in iter(param) do
+>                local name = item:display_name_of(p)
+>                local tp  = item:type_of_param(p)
+* **$(name)**($(tp)):$(item.params.map[p])
+>                if tp ~= '' then
+>                end -- if tp
+>
+>             end -- for p
+>          end -- for par
+>       end -- if item.params and #item.params > 0
+>
+>       -- print the returns
+>       if item.retgroups then
+>           local groups = item.retgroups
+
+**Returns:**
+
+>          for i, group in ldoc.ipairs(groups) do
+>             for r in group:iter() do
+>                local type, ctypes = item:return_type(r);
+* `$(type)`: $(r.text)
+>             end -- for r in group:iter()
+>          end -- for i,group
+>       end -- if item.retgroups
+
+>       if item.usage then
+**Usage**
+
+>          for usage in item.usage:iter() do
+```lua
+$(trim_newline(usage))
+```
+>          end -- for usage in item.usage:iter()
+>          local usage = item.usage
+>       end -- if item.usage
+>    end -- end for item in items()
+> end -- for kinds, items