diff options
Diffstat (limited to 'Server/Plugins')
| -rw-r--r-- | Server/Plugins/APIDump/APIDesc.lua | 13 | ||||
| -rw-r--r-- | Server/Plugins/APIDump/main_APIDump.lua | 113 | ||||
| m--------- | Server/Plugins/Core | 0 |
3 files changed, 111 insertions, 15 deletions
diff --git a/Server/Plugins/APIDump/APIDesc.lua b/Server/Plugins/APIDump/APIDesc.lua index 187c72b9e..2fcd02a17 100644 --- a/Server/Plugins/APIDump/APIDesc.lua +++ b/Server/Plugins/APIDump/APIDesc.lua @@ -1008,16 +1008,20 @@ local Hash = cCryptoHash.sha1HexString("DataToHash") Provides helper functions for manipulating and querying the filesystem. Most functions are static, so they should be called directly on the cFile class itself: <pre class="prettyprint lang-lua"> -cFile:Delete("/usr/bin/virus.exe"); +cFile:DeleteFile("/usr/bin/virus.exe"); </pre></p> ]], Functions = { ChangeFileExt = { Params = "FileName, NewExt", Return = "string", Notes = "(STATIC) Returns FileName with its extension changed to NewExt. NewExt may begin with a dot, but needn't, the result is the same in both cases (the first dot, if present, is ignored). FileName may contain path elements, extension is recognized as the last dot after the last path separator in the string." }, Copy = { Params = "SrcFileName, DstFileName", Return = "bool", Notes = "(STATIC) Copies a single file to a new destination. Returns true if successful. Fails if the destination already exists." }, - CreateFolder = { Params = "FolderName", Return = "bool", Notes = "(STATIC) Creates a new folder. Returns true if successful." }, - Delete = { Params = "FileName", Return = "bool", Notes = "(STATIC) Deletes the specified file. Returns true if successful." }, - Exists = { Params = "FileName", Return = "bool", Notes = "(STATIC) Returns true if the specified file exists." }, + CreateFolder = { Params = "FolderPath", Return = "bool", Notes = "(STATIC) Creates a new folder. Returns true if successful. Only a single level can be created at a time, use CreateFolderRecursive() to create multiple levels of folders at once." }, + CreateFolderRecursive = { Params = "FolderPath", Return = "bool", Notes = "(STATIC) Creates a new folder, creating its parents if needed. Returns true if successful." }, + Delete = { Params = "Path", Return = "bool", Notes = "(STATIC) Deletes the specified file or folder. Returns true if successful. Only deletes folders that are empty.<br/><b>NOTE</b>: If you already know if the object is a file or folder, use DeleteFile() or DeleteFolder() explicitly." }, + DeleteFile = { Params = "FilePath", Return = "bool", Notes = "(STATIC) Deletes the specified file. Returns true if successful." }, + DeleteFolder = { Params = "FolderPath", Return = "bool", Notes = "(STATIC) Deletes the specified file or folder. Returns true if successful. Only deletes folders that are empty." }, + DeleteFolderContents = { Params = "FolderPath", Return = "bool", Notes = "(STATIC) Deletes everything from the specified folder, recursively. The specified folder stays intact. Returns true if successful." }, + Exists = { Params = "Path", Return = "bool", Notes = "(STATIC) Returns true if the specified file or folder exists.<br/><b>OBSOLETE</b>, use IsFile() or IsFolder() instead" }, GetExecutableExt = { Params = "", Return = "string", Notes = "(STATIC) Returns the customary executable extension (including the dot) used by the current platform (\".exe\" on Windows, empty string on Linux). " }, GetFolderContents = { Params = "FolderName", Return = "array table of strings", Notes = "(STATIC) Returns the contents of the specified folder, as an array table of strings. Each filesystem object is listed. Use the IsFile() and IsFolder() functions to determine the object type." }, GetLastModificationTime = { Params = "Path", Return = "number", Notes = "(STATIC) Returns the last modification time (in current timezone) of the specified file or folder. Returns zero if file not found / not accessible. The returned value is in the same units as values returned by os.time()." }, @@ -3025,6 +3029,7 @@ end "cFurnaceEntity.__cBlockEntityWindowOwner__", "cHopperEntity.__cBlockEntityWindowOwner__", "cLuaWindow.__cItemGrid__cListener__", + "Globals._CuberiteInternal_.*", -- Ignore all internal Cuberite constants }, IgnoreVariables = diff --git a/Server/Plugins/APIDump/main_APIDump.lua b/Server/Plugins/APIDump/main_APIDump.lua index c0685087a..7cbd0d160 100644 --- a/Server/Plugins/APIDump/main_APIDump.lua +++ b/Server/Plugins/APIDump/main_APIDump.lua @@ -174,11 +174,9 @@ local function WriteArticles(f) ]]); for _, extra in ipairs(g_APIDesc.ExtraPages) do local SrcFileName = g_PluginFolder .. "/" .. extra.FileName; - if (cFile:Exists(SrcFileName)) then + if (cFile:IsFile(SrcFileName)) then local DstFileName = "API/" .. extra.FileName; - if (cFile:Exists(DstFileName)) then - cFile:Delete(DstFileName); - end + cFile:Delete(DstFileName); cFile:Copy(SrcFileName, DstFileName); f:write("<li><a href=\"" .. extra.FileName .. "\">" .. extra.Title .. "</a></li>\n"); else @@ -1002,7 +1000,7 @@ local function ListUndocumentedObjects(API, UndocumentedHooks) if (HasFunctions or HasConstants or HasVariables) then f:write("\t\t" .. cls.Name .. " =\n\t\t{\n"); if ((cls.Desc == nil) or (cls.Desc == "")) then - f:write("\t\t\tDesc = \"\"\n"); + f:write("\t\t\tDesc = \"\",\n"); end end @@ -1112,7 +1110,7 @@ local function ListMissingPages() local NumLinks = 0; for PageName, Referrers in pairs(g_TrackedPages) do NumLinks = NumLinks + 1; - if not(cFile:Exists("API/" .. PageName .. ".html")) then + if not(cFile:IsFile("API/" .. PageName .. ".html")) then table.insert(MissingPages, {Name = PageName, Refs = Referrers} ); end end; @@ -1566,9 +1564,8 @@ end -local function DumpApi() - LOG("Dumping the API...") - +--- Prepares the API and Globals tables containing the documentation +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 dofile(g_PluginFolder .. "/APIDesc.lua") @@ -1618,6 +1615,19 @@ local function DumpApi() LOG("Reading descriptions..."); ReadDescriptions(API); + return API, Globals +end + + + + + +local function DumpApi() + LOG("Dumping the API...") + + -- Match the currently exported API with the available documentation: + local API, Globals = PrepareApi() + -- Check that the API lists the inheritance properly, report any problems to a file: CheckAPIDescendants(API) @@ -1668,6 +1678,86 @@ end +local function HandleCmdApiCheck(a_Split, a_EntireCmd) + -- 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")) + local OfficialStats = cFile:ReadWholeFile("official_undocumented.lua") + if (OfficialStats == "") then + return true, "Cannot load official stats" + end + + -- Load the API stats as a Lua file, process into usable dictionary: + local Loaded, Msg = loadstring(OfficialStats) + if not(Loaded) then + return true, "Cannot load official stats: " .. (Msg or "<unknown error>") + end + local OfficialStatsDict = {} + setfenv(Loaded, OfficialStatsDict) + local IsSuccess, ErrMsg = pcall(Loaded) + if not(IsSuccess) then + return true, "Cannot parse official stats: " .. tostring(ErrMsg or "<unknown error>") + end + local Parsed = {} + for clsK, clsV in pairs(OfficialStatsDict.g_APIDesc.Classes) do + local cls = + { + Desc = not(clsV.Desc), -- set to true if the Desc was not documented in the official docs + Functions = {}, + Constants = {} + } + for funK, _ in pairs(clsV.Functions or {}) do + cls.Functions[funK] = true + end + for conK, _ in pairs(clsV.Constants or {}) do + cls.Constants[conK] = true + end + Parsed[clsK] = cls + end + + -- Get the current API's undocumented stats: + local API = PrepareApi() + + -- Compare the two sets of undocumented stats, list anything extra in current: + local res = {} + local ins = table.insert + for _, cls in ipairs(API) do + local ParsedOfficial = Parsed[cls.Name] or {} + if (not(cls.Desc) and ParsedOfficial.Desc) then + ins(res, cls.Name .. ".Desc") + end + local ParsedOfficialFns = ParsedOfficial.Functions or {} + for _, funK in ipairs(cls.UndocumentedFunctions or {}) do + if not(ParsedOfficialFns[funK]) then + ins(res, cls.Name .. "." .. funK .. " (function)") + end + end + local ParsedOfficialCons = ParsedOfficial.Constants or {} + for _, conK in ipairs(cls.UndocumentedConstants or {}) do + if not(ParsedOfficialCons[conK]) then + ins(res, cls.Name .. "." .. conK .. " (constant)") + end + end + end + table.sort(res) + + -- Bail out if no items found: + if not(res[1]) then + return true, "No new undocumented functions" + end + + -- Save any found items to a file: + local f = io.open("NewlyUndocumented.lua", "w") + f:write(table.concat(res, "\n")) + f:close() + + return true, "Newly undocumented items: " .. #res .. "\n" .. table.concat(res, "\n") +end + + + + + function Initialize(Plugin) g_Plugin = Plugin; g_PluginFolder = Plugin:GetLocalFolder(); @@ -1675,8 +1765,9 @@ function Initialize(Plugin) LOG("Initialising " .. Plugin:GetName() .. " v." .. Plugin:GetVersion()) -- Bind a console command to dump the API: - cPluginManager:BindConsoleCommand("api", HandleCmdApi, "Dumps the Lua API docs into the API/ subfolder") - cPluginManager:BindConsoleCommand("apishow", HandleCmdApiShow, "Runs the default browser to show the API docs") + cPluginManager:BindConsoleCommand("api", HandleCmdApi, "Dumps the Lua API docs into the API/ subfolder") + cPluginManager:BindConsoleCommand("apicheck", HandleCmdApiCheck, "Checks the Lua API documentation stats against the official stats") + cPluginManager:BindConsoleCommand("apishow", HandleCmdApiShow, "Runs the default browser to show the API docs") -- Add a WebAdmin tab that has a Dump button g_Plugin:AddWebTab("APIDump", HandleWebAdminDump) diff --git a/Server/Plugins/Core b/Server/Plugins/Core -Subproject ee01115ac848116cf58956fa6d031dbbadddba0 +Subproject b1e3f972ebf475bfbe1dfc8bccc0240977d11d3 |