From 905cd0e73ec9b54e9d4b9a7954c57161be40d491 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 15 Nov 2013 22:39:02 +0100 Subject: [PATCH 1/2] APIDump: Functions that are documented are never ignored. This simplifies exclude-filters for functions such as lxp.new() that need inclusion. --- MCServer/Plugins/APIDump/main.lua | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main.lua index d84926b53..ab154dc45 100644 --- a/MCServer/Plugins/APIDump/main.lua +++ b/MCServer/Plugins/APIDump/main.lua @@ -373,13 +373,18 @@ function ReadDescriptions(a_API) return false; end - -- Returns true if the function (specified by its fully qualified name) is to be ignored - local function IsFunctionIgnored(a_FnName) + -- Returns true if the function is to be ignored + local function IsFunctionIgnored(a_ClassName, a_FnName) if (g_APIDesc.IgnoreFunctions == nil) then return false; end + if (((g_APIDesc.Classes[a_ClassName] or {}).Functions or {})[a_FnName] ~= nil) then + -- The function is documented, don't ignore + return false; + end + local FnName = a_ClassName .. "." .. a_FnName; for i, name in ipairs(g_APIDesc.IgnoreFunctions) do - if (a_FnName:match(name)) then + if (FnName:match(name)) then return true; end end @@ -482,7 +487,7 @@ function ReadDescriptions(a_API) if (FnDesc == nil) then -- No description for this API function AddFunction(func.Name); - if not(IsFunctionIgnored(cls.Name .. "." .. FnName)) then + if not(IsFunctionIgnored(cls.Name, FnName)) then table.insert(cls.UndocumentedFunctions, FnName); end else @@ -505,7 +510,7 @@ function ReadDescriptions(a_API) else -- if (APIDesc.Functions ~= nil) for j, func in ipairs(cls.Functions) do local FnName = func.DocID or func.Name; - if not(IsFunctionIgnored(cls.Name .. "." .. FnName)) then + if not(IsFunctionIgnored(cls.Name, FnName)) then table.insert(cls.UndocumentedFunctions, FnName); end end @@ -567,7 +572,7 @@ function ReadDescriptions(a_API) g_Stats.NumUndocumentedClasses = g_Stats.NumUndocumentedClasses + 1; for j, func in ipairs(cls.Functions) do local FnName = func.DocID or func.Name; - if not(IsFunctionIgnored(cls.Name .. "." .. FnName)) then + if not(IsFunctionIgnored(cls.Name, FnName)) then table.insert(cls.UndocumentedFunctions, FnName); end end -- for j, func - cls.Functions[] @@ -586,7 +591,7 @@ function ReadDescriptions(a_API) -- Remove ignored functions: local NewFunctions = {}; for j, fn in ipairs(cls.Functions) do - if (not(IsFunctionIgnored(cls.Name .. "." .. fn.Name))) then + if (not(IsFunctionIgnored(cls.Name, fn.Name))) then table.insert(NewFunctions, fn); end end -- for j, fn From d96f6224371a0c6aaf561f16d31381e5b11e5a55 Mon Sep 17 00:00:00 2001 From: madmaxoft Date: Fri, 15 Nov 2013 22:39:27 +0100 Subject: [PATCH 2/2] APIDump: Documented lxp, the XML parser class. --- MCServer/Plugins/APIDump/APIDesc.lua | 106 +++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 741b912a6..cccc05ce2 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -2478,6 +2478,112 @@ end }, }, -- ItemCategory + lxp = + { + Desc = [[ + This class provides an interface to the XML parser, + {{http://matthewwild.co.uk/projects/luaexpat/|LuaExpat}}. It provides a SAX interface with an + incremental XML parser.

+

+ With an event-based API like SAX the XML document can be fed to the parser in chunks, and the + parsing begins as soon as the parser receives the first document chunk. LuaExpat reports parsing + events (such as the start and end of elements) directly to the application through callbacks. The + parsing of huge documents can benefit from this piecemeal operation.

+

+ See the online + {{http://matthewwild.co.uk/projects/luaexpat/manual.html#parser|LuaExpat documentation}} for details + on how to work with this parser. The code examples below should provide some basic help, too. + ]], + Functions = + { + new = {Params = "CallbacksTable, [SeparatorChar]", Return = "XMLParser object", Notes = "Creates a new XML parser object, with the specified callbacks table and optional separator character."}, + }, + Constants = + { + _COPYRIGHT = { Notes = "" }, + _DESCRIPTION = { Notes = "" }, + _VERSION = { Notes = "" }, + }, + AdditionalInfo = + { + { + Header = "Parser callbacks", + Contents = [[ + The callbacks table passed to the new() function specifies the Lua functions that the parser + calls upon various events. The following table lists the most common functions used, for a + complete list see the online + {{http://matthewwild.co.uk/projects/luaexpat/manual.html#parser|LuaExpat documentation}}.

+ + + + + +
Function nameParametersNotes
CharacterDataParser, stringCalled when the parser recognizes a raw string inside the element
EndElementParser, ElementNameCalled when the parser detects the ending of an XML element
StartElementParser, ElementName, AttributesTableCalled when the parser detects the start of an XML element. The AttributesTable is a Lua table containing all the element's attributes, both in the array section (in the order received) and in the dictionary section.
+ ]], + }, + { + Header = "XMLParser object", + Contents = [[ + The XMLParser object returned by lxp.new provides the functions needed to parse the XML. The + following list provides the most commonly used ones, for a complete list see the online + {{http://matthewwild.co.uk/projects/luaexpat/manual.html#parser|LuaExpat documentation}}. + + ]], + }, + { + Header = "Code example", + Contents = [[ + The following code reads an entire XML file and outputs its logical structure into the console: +
+local Depth = 0;
+
+-- Define the callbacks:
+local Callbacks = {
+	CharacterData = function(a_Parser, a_String)
+		LOG(string.rep(" ", Depth) .. "* " .. a_String);
+	end
+	
+	EndElement = function(a_Parser, a_ElementName)
+		Depth = Depth - 1;
+		LOG(string.rep(" ", Depth) .. "- " .. a_ElementName);
+	end
+
+	StartElement = function(a_Parser, a_ElementName, a_Attribs)
+		LOG(string.rep(" ", Depth) .. "+ " .. a_ElementName);
+		Depth = Depth + 1;
+	end
+}
+
+-- Create the parser:
+local Parser = lxp.new(Callbacks);
+
+-- Parse the XML file:
+local f = io.open("file.xml", "rb");
+while (true) do
+	local block = f:read(128 * 1024);  -- Use a 128KiB buffer for reading
+	if (block == nil) then
+		-- End of file
+		break;
+	end
+	Parser:parse(block);
+end
+
+-- Signalize to the parser that no more data is coming
+Parser:parse();
+
+-- Close the parser:
+Parser:close();
+
+ ]], + }, + }, -- AdditionalInfo + }, -- lxp + TakeDamageInfo = { Desc = [[