summaryrefslogtreecommitdiffstats
path: root/Server/Plugins/APIDump/main_APIDump.lua
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--Server/Plugins/APIDump/main_APIDump.lua189
1 files changed, 152 insertions, 37 deletions
diff --git a/Server/Plugins/APIDump/main_APIDump.lua b/Server/Plugins/APIDump/main_APIDump.lua
index 6dec8e159..c2d70734d 100644
--- a/Server/Plugins/APIDump/main_APIDump.lua
+++ b/Server/Plugins/APIDump/main_APIDump.lua
@@ -1816,43 +1816,12 @@ end
-local function HandleWebAdminDump(a_Request)
- if (a_Request.PostParams["Dump"] ~= nil) then
- DumpApi()
- end
- return
- [[
- <p>Pressing the button will generate the API dump on the server. Note that this can take some time.</p>
- <form method="POST"><input type="submit" name="Dump" value="Dump the API"/></form>
- ]]
-end
-
-
-
-
-
-local function HandleCmdApi(a_Split)
- DumpApi()
- return true
-end
-
-
-
-
-
-local function HandleCmdApiShow(a_Split, a_EntireCmd)
- os.execute("API" .. cFile:GetPathSeparator() .. "index.html")
- return true, "Launching the browser to show the API docs..."
-end
-
-
-
-
-
-local function HandleCmdApiCheck(a_Split, a_EntireCmd)
+--- Checks the currently undocumented symbols against an "official" undocumented symbol list
+-- Returns an array-table of strings representing the newly-undocumented symbol names
+local function CheckNewUndocumentedSymbols()
-- Download the official API stats on undocumented stuff:
-- (We need a blocking downloader, which is impossible with the current cNetwork API)
- assert(os.execute("wget -O official_undocumented.lua http://apidocs.cuberite.org/_undocumented.lua"))
+ assert(os.execute("wget -q -O official_undocumented.lua http://apidocs.cuberite.org/_undocumented.lua"))
local OfficialStats = cFile:ReadWholeFile("official_undocumented.lua")
if (OfficialStats == "") then
return true, "Cannot load official stats"
@@ -1916,7 +1885,7 @@ local function HandleCmdApiCheck(a_Split, a_EntireCmd)
-- Bail out if no items found:
if not(res[1]) then
- return true, "No new undocumented functions"
+ return
end
-- Save any found items to a file:
@@ -1925,7 +1894,153 @@ local function HandleCmdApiCheck(a_Split, a_EntireCmd)
f:write("\n")
f:close()
- return true, "Newly undocumented items: " .. #res .. "\n" .. table.concat(res, "\n")
+ return res
+end
+
+
+
+
+
+--- Checks the API description for unknown types listed in Params or Returns
+-- Returns an array-table of { Location = "cClass:function(), param #1", Type = "UnknownType" }
+-- Returns nil if no unknown types are found
+local function CheckBadTypes()
+ -- Load the API and preprocess known types:
+ local api = PrepareApi()
+ local knownTypes =
+ {
+ string = true,
+ number = true,
+ boolean = true,
+ any = true,
+ self = true,
+ table = true,
+ ["function"] = true,
+ ["..."] = true,
+ ["SQLite DB object"] = true,
+ ["<unknown>"] = true, -- Allow "<unknown>" types, for now, until the API is properly documented
+ }
+ for _, clsDesc in ipairs(api) do
+ knownTypes[clsDesc.Name] = true -- The class is a known type
+ for grpName, _ in pairs(clsDesc.ConstantGroups or {}) do -- All class' enums are known types (with namespacing)
+ knownTypes[clsDesc.Name .. "#" .. grpName] = true
+ end
+ if (clsDesc.Name == "Globals") then
+ for grpName, _ in pairs(clsDesc.ConstantGroups or {}) do -- All Globals' enums are known types without namespacing, too
+ knownTypes[grpName] = true
+ end
+ end
+ end -- for cls - classes
+
+ -- Check types:
+ local res = {}
+ for _, clsDesc in ipairs(api) do
+ for _, fnDesc in ipairs(clsDesc.Functions or {}) do
+ local fnName = fnDesc.Name
+ local fn = fnDesc[1] and fnDesc or { fnDesc } -- Unify the format, fn is an array of function signatures
+ for idxS, signature in ipairs(fn) do
+ for idxP, param in ipairs(signature.Params or {}) do
+ if not(knownTypes[param.Type]) then
+ table.insert(res, {
+ Location = string.format("%s:%s(), signature #%d, param #%d", clsDesc.Name, fnName, idxS, idxP),
+ Type = param.Type,
+ })
+ end
+ end -- for param
+ if (type(signature.Returns) == "table") then
+ for idxR, ret in ipairs(signature.Returns) do
+ if not(knownTypes[ret.Type]) then
+ table.insert(res, {
+ Location = string.format("%s:%s(), signature #%d, return #%d", clsDesc.Name, fnName, idxS, idxR),
+ Type = ret.Type,
+ })
+ end
+ end -- for ret
+ elseif not(signature.Returns) then
+ else
+ table.insert(res, {
+ Location = string.format("%s:%s(), signature #%d, return string", clsDesc.Name, fnName, idxS),
+ Type = tostring(signature.Returns),
+ })
+ end
+ end -- for signature
+ end -- for fn - functions
+ end -- for cls - classes
+
+ -- If no problems found, bail out:
+ if not(res[1]) then
+ return
+ end
+
+ -- Write the problems into a file:
+ local f = io.open("UnknownTypes.lua", "w")
+ f:write("return\n{\n")
+ for _, item in ipairs(res) do
+ f:write("\t{ ", string.format("{ Location = %q, Type = %q", item.Location, item.Type), "},\n")
+ end
+ f:write("}\n")
+ f:close()
+ return res
+end
+
+
+
+
+
+local function HandleWebAdminDump(a_Request)
+ if (a_Request.PostParams["Dump"] ~= nil) then
+ DumpApi()
+ end
+ return
+ [[
+ <p>Pressing the button will generate the API dump on the server. Note that this can take some time.</p>
+ <form method="POST"><input type="submit" name="Dump" value="Dump the API"/></form>
+ ]]
+end
+
+
+
+
+
+local function HandleCmdApi(a_Split)
+ DumpApi()
+ return true
+end
+
+
+
+
+
+local function HandleCmdApiShow(a_Split, a_EntireCmd)
+ os.execute("API" .. cFile:GetPathSeparator() .. "index.html")
+ return true, "Launching the browser to show the API docs..."
+end
+
+
+
+
+
+local function HandleCmdApiCheck(a_Split, a_EntireCmd)
+ -- Check the Params and Returns types:
+ LOG("Checking API for bad types...")
+ local badTypes = CheckBadTypes()
+ if (badTypes) then
+ -- Serialize into descriptions:
+ local descs = {}
+ for idx, t in ipairs(badTypes) do
+ descs[idx] = string.format("Location %q, type %q", t.Location, t.Type)
+ end
+ return true, "Found bad types:\n" .. table.concat(descs, "\n")
+ end
+
+ -- Check for new symbols that are not documented:
+ LOG("Checking API for newly undocumented symbols...")
+ local newUndocumented = CheckNewUndocumentedSymbols()
+ if (newUndocumented) then
+ return true, "Found new undocumented symbols:\n" .. table.concat(newUndocumented, "\n")
+ end
+
+ return true, "API check completed successfully"
end