From 08861becc3f575bdf9aaad76e3b8964ddc322d3f Mon Sep 17 00:00:00 2001 From: Mattes D Date: Fri, 9 Sep 2016 11:19:22 +0200 Subject: APIDump: Support structured parameter info. Ref.: GH#3375 --- Server/Plugins/APIDump/main_APIDump.lua | 117 ++++++++++++++++++++++++++------ 1 file changed, 96 insertions(+), 21 deletions(-) (limited to 'Server/Plugins/APIDump/main_APIDump.lua') diff --git a/Server/Plugins/APIDump/main_APIDump.lua b/Server/Plugins/APIDump/main_APIDump.lua index 47848c26a..ebca6b4f0 100644 --- a/Server/Plugins/APIDump/main_APIDump.lua +++ b/Server/Plugins/APIDump/main_APIDump.lua @@ -146,6 +146,12 @@ local function CreateAPITables() end end + -- Remove the built-in Lua libraries: + API.debug = nil + API.io = nil + API.string = nil + API.table = nil + return API, Globals; end @@ -676,13 +682,6 @@ local function ReadDescriptions(a_API, a_Desc) -- Sort the functions (they may have been renamed): table.sort(cls.Functions, function(f1, f2) - if (f1.Name == f2.Name) then - -- Same name, either comparing the same function to itself, or two overloads, in which case compare the params - if ((f1.Params == nil) or (f2.Params == nil)) then - return 0; - end - return (f1.Params < f2.Params); - end return (f1.Name < f2.Name); end ); @@ -761,7 +760,86 @@ end -local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) +--- Returns a HTML string describing the (parameter) type, linking to the type's documentation, if available +-- a_Type is the string containing the type (such as "cPlugin" or "number"), or nil +-- a_API is the complete API description (used for searching the classnames) +local function LinkifyType(a_Type, a_API) + -- Check params: + assert(type(a_Type) == "string") + assert(type(a_API) == "table") + + -- If the type is a known class, return a direct link to it: + if (a_API[a_Type]) then + return "" .. a_Type .. "" + end + + -- If the type has a colon, it's a child enum of a class: + local idxColon = a_Type:find(":") + if (idxColon) then + local classType = a_Type:sub(1, idxColon - 1) + if (a_API[classType]) then + local enumType = a_Type:sub(idxColon + 2) + return "" .. a_Type .. "" + end + end + + -- Unknown or built-in type, output just text: + return a_Type +end + + + + + +--- Returns an HTML string describing all function parameters (or return values) +-- a_FnParams is an array-table or string description of the parameters +-- a_ClassName is the name of the class for which the function is being documented (for Linkification) +-- a_API is the complete API description (for cross-type linkification) +local function CreateFunctionParamsDescription(a_FnParams, a_ClassName, a_API) + local pt = type(a_FnParams) + assert((pt == "string") or (pt == "table")) + assert(type(a_ClassName) == "string") + assert(type(a_API) == "table") + + -- If the params description is a string (old format), just linkify it: + if (pt == "string") then + return LinkifyString(a_FnParams, a_ClassName) + end + + -- If the params description is an empty table, give no description at all: + if not(a_FnParams[1]) then + return "" + end + + -- The params description is a table, output the full desc: + local res = {""} + local idx = 2 + for _, param in ipairs(a_FnParams) do + res[idx] = "" + idx = idx + 5 + end + res[idx] = "
" + res[idx + 1] = param.Name or "" + res[idx + 2] = "" + res[idx + 3] = LinkifyType(param.Type, a_API) + res[idx + 4] = "
" + return table.concat(res) +end + + + + + +--- Writes an HTML file containing the class API description for the given class +-- a_ClassAPI is the API description of the class to output +-- a_ClassMenu is the HTML string containing the code for the menu sidebar +-- a_API is the complete API (for cross-type linkification) +local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API) + -- Check params: + assert(type(a_ClassAPI) == "table") + assert(type(a_ClassMenu) == "string") + assert(type(a_API) == "table") + local cf, err = io.open("API/" .. a_ClassAPI.Name .. ".html", "w"); if (cf == nil) then LOGINFO("Cannot write HTML API for class " .. a_ClassAPI.Name .. ": " .. err) @@ -770,11 +848,12 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) -- Writes a table containing all functions in the specified list, with an optional "inherited from" header when a_InheritedName is valid local function WriteFunctions(a_Functions, a_InheritedName) - if (#a_Functions == 0) then + if not(a_Functions[1]) then + -- No functions to write return; end - if (a_InheritedName ~= nil) then + if (a_InheritedName) then cf:write("

Functions inherited from ", a_InheritedName, "

\n"); end cf:write("\n\n"); @@ -789,8 +868,8 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu) TableOverloadedFunctions[func.Name] = (TableOverloadedFunctions[func.Name] or 0) + 1 -- Add the anchor names as a title cf:write("\n"); - cf:write("\n"); - cf:write("\n"); + cf:write("\n"); + cf:write("\n"); cf:write("\n"); end cf:write("
NameParametersReturn valueNotes
", func.Name, "", LinkifyString(func.Params or "", (a_InheritedName or a_ClassAPI.Name)), "", LinkifyString(func.Return or "", (a_InheritedName or a_ClassAPI.Name)), "", CreateFunctionParamsDescription(func.Params or {}, a_InheritedName or a_ClassAPI.Name, a_API), "", CreateFunctionParamsDescription(func.Return or {}, a_InheritedName or a_ClassAPI.Name, a_API), "", StaticClause .. LinkifyString(func.Notes or "(undocumented)", (a_InheritedName or a_ClassAPI.Name)), "
\n"); @@ -1032,7 +1111,7 @@ local function WriteClasses(f, a_API, a_ClassMenu) ]]); for _, cls in ipairs(a_API) do f:write("
  • ", cls.Name, "
    • \n"); - WriteHtmlClass(cls, a_ClassMenu); + WriteHtmlClass(cls, a_ClassMenu, a_API); end f:write([[

    @@ -1648,14 +1727,10 @@ local function PrepareApi() -- Load the API descriptions from the Classes and Hooks subfolders: -- This needs to be done each time the command is invoked because the export modifies the tables' contents local apiDesc = dofile(g_PluginFolder .. "/APIDesc.lua") - if (apiDesc.Classes == nil) then - apiDesc.Classes = {}; - end - if (apiDesc.Hooks == nil) then - apiDesc.Hooks = {}; - end - LoadAPIFiles("/Classes/", apiDesc.Classes); - LoadAPIFiles("/Hooks/", apiDesc.Hooks); + apiDesc.Classes = apiDesc.Classes or {} + apiDesc.Hooks = apiDesc.Hooks or {} + LoadAPIFiles("/Classes/", apiDesc.Classes) + LoadAPIFiles("/Hooks/", apiDesc.Hooks) -- Reset the stats: g_TrackedPages = {}; -- List of tracked pages, to be checked later whether they exist. Each item is an array of referring pagenames. -- cgit v1.2.3