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

Author: tzssangglass

.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