You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by bz...@apache.org on 2022/03/02 03:19:58 UTC
[apisix] branch master updated: docs: automatic generate PDK docs by LDoc (#6321)
This is an automated email from the ASF dual-hosted git repository.
bzp2010 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 0fd582b docs: automatic generate PDK docs by LDoc (#6321)
0fd582b is described below
commit 0fd582bc299a9d90893d3843cd3ec21f217cb40e
Author: tzssangglass <tz...@gmail.com>
AuthorDate: Wed Mar 2 11:19:50 2022 +0800
docs: automatic generate PDK docs by LDoc (#6321)
---
.licenserc.yaml | 1 +
apisix/core/config_etcd.lua | 26 ++++++++++++
apisix/core/config_local.lua | 26 +++++++++++-
apisix/core/config_util.lua | 13 ++++++
apisix/core/config_yaml.lua | 5 +++
apisix/core/ctx.lua | 24 +++++++++++
apisix/core/dns/client.lua | 5 +++
apisix/core/etcd.lua | 18 +++++++-
apisix/core/id.lua | 13 +++++-
apisix/core/io.lua | 16 +++++++-
apisix/core/ip.lua | 16 +++++++-
apisix/core/json.lua | 19 ++++++++-
apisix/core/log.lua | 16 ++++++++
apisix/core/lrucache.lua | 22 ++++++++++
apisix/core/os.lua | 16 +++++++-
apisix/core/profile.lua | 18 +++++++-
apisix/core/request.lua | 24 ++++++++++-
apisix/core/resolver.lua | 14 ++++++-
apisix/core/response.lua | 12 +++++-
apisix/core/schema.lua | 4 ++
apisix/core/string.lua | 15 ++++++-
apisix/core/table.lua | 16 +++++++-
apisix/core/timer.lua | 5 +++
apisix/core/utils.lua | 12 ++++++
apisix/core/vault.lua | 5 +++
apisix/core/version.lua | 5 +++
autodocs/config.ld | 11 +++++
autodocs/generate.sh | 51 +++++++++++++++++++++++
autodocs/ldoc.ltp | 98 ++++++++++++++++++++++++++++++++++++++++++++
29 files changed, 511 insertions(+), 15 deletions(-)
diff --git a/.licenserc.yaml b/.licenserc.yaml
index 9d71547..d2ce2e6 100644
--- a/.licenserc.yaml
+++ b/.licenserc.yaml
@@ -42,5 +42,6 @@ header:
# Exclude plugin-specific configuration files
- 't/plugin/authz-casbin'
- 't/coredns'
+ - 'autodocs/'
comment: on-failure
diff --git a/apisix/core/config_etcd.lua b/apisix/core/config_etcd.lua
index dc7fc38..9d70ce9 100644
--- a/apisix/core/config_etcd.lua
+++ b/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
diff --git a/apisix/core/config_local.lua b/apisix/core/config_local.lua
index 9494dad..cf44fee 100644
--- a/apisix/core/config_local.lua
+++ b/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
diff --git a/apisix/core/config_util.lua b/apisix/core/config_util.lua
index 4f13966..ae8ffdf 100644
--- a/apisix/core/config_util.lua
+++ b/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
diff --git a/apisix/core/config_yaml.lua b/apisix/core/config_yaml.lua
index e8eabb6..0a57828 100644
--- a/apisix/core/config_yaml.lua
+++ b/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")
diff --git a/apisix/core/ctx.lua b/apisix/core/ctx.lua
index fc1d3f8..edd3f37 100644
--- a/apisix/core/ctx.lua
+++ b/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")
diff --git a/apisix/core/dns/client.lua b/apisix/core/dns/client.lua
index 7d60aee..b9dcfb9 100644
--- a/apisix/core/dns/client.lua
+++ b/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")
diff --git a/apisix/core/etcd.lua b/apisix/core/etcd.lua
index 9c29162..9d289bd 100644
--- a/apisix/core/etcd.lua
+++ b/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
diff --git a/apisix/core/id.lua b/apisix/core/id.lua
index 7ca8cf1..8f6f6a4 100644
--- a/apisix/core/id.lua
+++ b/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
diff --git a/apisix/core/io.lua b/apisix/core/io.lua
index 1c70256..ad1b229 100644
--- a/apisix/core/io.lua
+++ b/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
diff --git a/apisix/core/ip.lua b/apisix/core/ip.lua
index 2dc8313..5a762be 100644
--- a/apisix/core/ip.lua
+++ b/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, "/")
diff --git a/apisix/core/json.lua b/apisix/core/json.lua
index 2d895b3..afad364 100644
--- a/apisix/core/json.lua
+++ b/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
diff --git a/apisix/core/log.lua b/apisix/core/log.lua
index a399113..b59e0b7 100644
--- a/apisix/core/log.lua
+++ b/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
diff --git a/apisix/core/lrucache.lua b/apisix/core/lrucache.lua
index 97c23ec..5c81dd3 100644
--- a/apisix/core/lrucache.lua
+++ b/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, ...)
diff --git a/apisix/core/os.lua b/apisix/core/os.lua
index 0edc319..ae721e8 100644
--- a/apisix/core/os.lua
+++ b/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
diff --git a/apisix/core/profile.lua b/apisix/core/profile.lua
index e7cd945..b4c4cfa 100644
--- a/apisix/core/profile.lua
+++ b/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
diff --git a/apisix/core/request.lua b/apisix/core/request.lua
index 1bd8aafe..c806719 100644
--- a/apisix/core/request.lua
+++ b/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
diff --git a/apisix/core/resolver.lua b/apisix/core/resolver.lua
index d6b76cd..056fbf8 100644
--- a/apisix/core/resolver.lua
+++ b/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
diff --git a/apisix/core/response.lua b/apisix/core/response.lua
index 221c184..29442df 100644
--- a/apisix/core/response.lua
+++ b/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
diff --git a/apisix/core/schema.lua b/apisix/core/schema.lua
index 8f79e96..9ce6a55 100644
--- a/apisix/core/schema.lua
+++ b/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})
diff --git a/apisix/core/string.lua b/apisix/core/string.lua
index ed7fef8..a6a7359 100644
--- a/apisix/core/string.lua
+++ b/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))
diff --git a/apisix/core/table.lua b/apisix/core/table.lua
index d0bc1b2..02fdb7a 100644
--- a/apisix/core/table.lua
+++ b/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
diff --git a/apisix/core/timer.lua b/apisix/core/timer.lua
index 514a5c1..7cd3c53 100644
--- a/apisix/core/timer.lua
+++ b/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
diff --git a/apisix/core/utils.lua b/apisix/core/utils.lua
index ad39bf2..f72996b 100644
--- a/apisix/core/utils.lua
+++ b/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
diff --git a/apisix/core/vault.lua b/apisix/core/vault.lua
index 0938aa7..aeb8485 100644
--- a/apisix/core/vault.lua
+++ b/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")
diff --git a/apisix/core/version.lua b/apisix/core/version.lua
index de741af..ae8e4f9 100644
--- a/apisix/core/version.lua
+++ b/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"
}
diff --git a/autodocs/config.ld b/autodocs/config.ld
new file mode 100644
index 0000000..d5d3cca
--- /dev/null
+++ b/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 = ">"
diff --git a/autodocs/generate.sh b/autodocs/generate.sh
new file mode 100755
index 0000000..4b918cd
--- /dev/null
+++ b/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
diff --git a/autodocs/ldoc.ltp b/autodocs/ldoc.ltp
new file mode 100644
index 0000000..72d77c2
--- /dev/null
+++ b/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