diff options
| -rw-r--r-- | MCServer/Plugins/APIDump/APIDesc.lua | 62 | ||||
| -rw-r--r-- | MCServer/Plugins/APIDump/main_APIDump.lua (renamed from MCServer/Plugins/APIDump/main.lua) | 100 |
2 files changed, 144 insertions, 18 deletions
diff --git a/MCServer/Plugins/APIDump/APIDesc.lua b/MCServer/Plugins/APIDump/APIDesc.lua index 8591d9aa4..5489650ad 100644 --- a/MCServer/Plugins/APIDump/APIDesc.lua +++ b/MCServer/Plugins/APIDump/APIDesc.lua @@ -30,6 +30,17 @@ g_APIDesc = { ConstantName = { Notes = "Notes about the constant" }, } , + + ConstantGroups = + { + GroupName1 = -- GroupName1 is used as the HTML anchor name + { + Include = {"constant1", "constant2", "const_.*"}, -- Constants to include in this group, array of identifiers, accepts wildcards + TextBefore = "This text will be written in front of the constant list", + TextAfter = "This text will be written after the constant list", + ShowInDescendants = false, -- If false, descendant classes won't list these constants + } + }, Variables = { @@ -75,6 +86,18 @@ g_APIDesc = psInSurvivalOrCreative = { Notes = "The arrow can be picked up by players in survival or creative gamemode" }, psNoPickup = { Notes = "The arrow cannot be picked up at all" }, }, + + ConstantGroups = + { + PickupState = + { + Include = "ps.*", + TextBefore = [[ + The following constants are used to signalize whether the arrow, once it lands, can be picked by + players: + ]], + }, + }, Inherits = "cProjectileEntity", }, @@ -182,7 +205,25 @@ g_APIDesc = msImprint = { Notes = "Src overwrites Dst anywhere where Dst has non-air blocks" }, msLake = { Notes = "Special mode for merging lake images" }, }, - + ConstantGroups = + { + BATypes = + { + Include = "ba.*", + TextBefore = [[ + The following constants are used to signalize the datatype to read or write: + ]], + }, + MergeStrategies = + { + Include = "ms.*", + TextBefore = [[ + The Merge() function can use different strategies to combine the source and destination blocks. + The following constants are used: + ]], + TextAfter = "See below for a detailed explanation of the individual merge strategies.", + }, + }, AdditionalInfo = { { @@ -817,7 +858,7 @@ end GetChunkZ = { Params = "", Return = "number", Notes = "Returns the Z-coord of the chunk in which the entity is placed" }, GetClass = { Params = "", Return = "string", Notes = "Returns the classname of the entity, such as \"cSpider\" or \"cPickup\"" }, GetClassStatic = { Params = "", Return = "string", Notes = "Returns the entity classname that this class implements. Each descendant overrides this function. Is static" }, - GetEntityType = { Params = "", Return = "eEntityType", Notes = "Returns the type of the entity, one of the etXXX constants. Note that to check specific entity type, you should use one of the IsXXX functions instead of comparing the value returned by this call." }, + GetEntityType = { Params = "", Return = "{{cEntity#EntityType|EntityType}}", Notes = "Returns the type of the entity, one of the {{cEntity#EntityType|etXXX}} constants. Note that to check specific entity type, you should use one of the IsXXX functions instead of comparing the value returned by this call." }, GetEquippedBoots = { Params = "", Return = "{{cItem}}", Notes = "Returns the boots that the entity has equipped. Returns an empty cItem if no boots equipped or not applicable." }, GetEquippedChestplate = { Params = "", Return = "{{cItem}}", Notes = "Returns the chestplate that the entity has equipped. Returns an empty cItem if no chestplate equipped or not applicable." }, GetEquippedHelmet = { Params = "", Return = "{{cItem}}", Notes = "Returns the helmet that the entity has equipped. Returns an empty cItem if no helmet equipped or not applicable." }, @@ -922,6 +963,14 @@ end etProjectile = { Notes = "The entity is a {{cProjectileEntity}} descendant" }, etTNT = { Notes = "The entity is a {{cTNTEntity}}" }, }, + ConstantGroups = + { + EntityType = + { + Include = "et.*", + TextBefore = "The following constants are used to distinguish between different entity types:", + }, + }, }, cFile = @@ -2018,12 +2067,21 @@ cPluginManager.AddHook(cPluginManager.HOOK_CHAT, OnChatMessage); pkEnderPearl = { Notes = "The projectile is a {{cThrownEnderPearlEntity|thrown enderpearl}}" }, pkExpBottle = { Notes = "The projectile is a thrown exp bottle (NYI)" }, pkFireCharge = { Notes = "The projectile is a {{cFireChargeEntity|fire charge}}" }, + pkFirework = { Notes = "The projectile is a (flying) firework (NYI)" }, pkFishingFloat = { Notes = "The projectile is a fishing float (NYI)" }, pkGhastFireball = { Notes = "The projectile is a {{cGhastFireballEntity|ghast fireball}}" }, pkSnowball = { Notes = "The projectile is a {{cThrownSnowballEntity|thrown snowball}}" }, pkSplashPotion = { Notes = "The projectile is a thrown splash potion (NYI)" }, pkWitherSkull = { Notes = "The projectile is a wither skull (NYI)" }, }, + ConstantGroups = + { + ProjectileKind = + { + Include = "pk.*", + TextBefore = "The following constants are used to distinguish between the different projectile kinds:", + }, + }, Inherits = "cEntity", }, diff --git a/MCServer/Plugins/APIDump/main.lua b/MCServer/Plugins/APIDump/main_APIDump.lua index fa9d29423..4dcedc06e 100644 --- a/MCServer/Plugins/APIDump/main.lua +++ b/MCServer/Plugins/APIDump/main_APIDump.lua @@ -38,7 +38,7 @@ function Initialize(Plugin) Plugin:SetName("APIDump"); Plugin:SetVersion(1); - LOG("Initialised " .. Plugin:GetName() .. " v." .. Plugin:GetVersion()) + LOG("Initialising " .. Plugin:GetName() .. " v." .. Plugin:GetVersion()) g_PluginFolder = Plugin:GetLocalFolder(); @@ -48,6 +48,8 @@ function Initialize(Plugin) -- Dump all available API object in HTML format into a subfolder: DumpAPIHtml(); + LOG("APIDump finished"); + return true end @@ -430,6 +432,11 @@ function ReadDescriptions(a_API) -- Process the documentation for each class: for i, cls in ipairs(a_API) do + -- Initialize default values for each class: + cls.ConstantGroups = {}; + cls.NumConstantsInGroups = 0; + cls.NumConstantsInGroupsForDescendants = 0; + -- Rename special functions: for j, fn in ipairs(cls.Functions) do if (fn.Name == ".call") then @@ -562,6 +569,52 @@ function ReadDescriptions(a_API) end end -- else if (APIDesc.Variables ~= nil) + if (APIDesc.ConstantGroups ~= nil) then + -- Create links between the constants and the groups: + local NumInGroups = 0; + local NumInDescendantGroups = 0; + for j, group in pairs(APIDesc.ConstantGroups) do + group.Name = j; + group.Constants = {}; + if (type(group.Include == "string")) then + group.Include = { group.Include }; + end + local NumInGroup = 0; + for idx, incl in ipairs(group.Include or {}) do + for cidx, cons in ipairs(cls.Constants) do + if ((cons.Group == nil) and cons.Name:match(incl)) then + cons.Group = group; + table.insert(group.Constants, cons); + NumInGroup = NumInGroup + 1; + end + end -- for cidx - cls.Constants[] + end -- for idx - group.Include[] + NumInGroups = NumInGroups + NumInGroup; + if (group.ShowInDescendants) then + NumInDescendantGroups = NumInDescendantGroups + NumInGroup; + end + + -- Sort the constants: + table.sort(group.Constants, + function(c1, c2) + return (c1.Name < c2.Name); + end + ); + end -- for j - APIDesc.ConstantGroups[] + cls.ConstantGroups = APIDesc.ConstantGroups; + cls.NumConstantsInGroups = NumInGroups; + cls.NumConstantsInGroupsForDescendants = NumInDescendantGroups; + + -- Remove grouped constants from the normal list: + local NewConstants = {}; + for idx, cons in ipairs(cls.Constants) do + if (cons.Group == nil) then + table.insert(NewConstants, cons); + end + end + cls.Constants = NewConstants; + end -- if (ConstantGroups ~= nil) + else -- if (APIDesc ~= nil) -- Class is not documented at all, add all its members to Undocumented lists: @@ -752,22 +805,37 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI) cf:write(" </table>\n\n"); end - local function WriteConstants(a_Constants, a_InheritedName) - if (#a_Constants == 0) then + local function WriteConstantTable(a_Constants, a_Source) + cf:write("<table>\n<tr><th>Name</th><th>Value</th><th>Notes</th></tr>\n"); + for i, cons in ipairs(a_Constants) do + cf:write("<tr><td>", cons.Name, "</td>\n"); + cf:write("<td>", cons.Value, "</td>\n"); + cf:write("<td>", LinkifyString(cons.Notes or "", a_Source), "</td></tr>\n"); + end + cf:write("</table>\n\n"); + end + + local function WriteConstants(a_Constants, a_ConstantGroups, a_NumConstantGroups, a_InheritedName) + if ((#a_Constants == 0) and (a_NumConstantGroups == 0)) then return; end if (a_InheritedName ~= nil) then - cf:write(" <h2>Constants inherited from ", a_InheritedName, "</h2>\n"); + cf:write("<h2>Constants inherited from ", a_InheritedName, "</h2>\n"); end - cf:write(" <table>\n <tr>\n <th>Name</th>\n <th>Value</th>\n <th>Notes</th>\n </tr>\n"); - for i, cons in ipairs(a_Constants) do - cf:write(" <tr>\n <td>", cons.Name, "</td>\n"); - cf:write(" <td>", cons.Value, "</td>\n"); - cf:write(" <td>", LinkifyString(cons.Notes or "", a_InheritedName or a_ClassAPI.Name), "</td>\n </tr>\n"); + if (#a_Constants > 0) then + WriteConstantTable(a_Constants, a_InheritedName or a_ClassAPI.Name); + end + + for k, group in pairs(a_ConstantGroups) do + if ((a_InheritedName == nil) or group.ShowInDescendants) then + cf:write("<a name='", group.Name, "'><p>"); + cf:write(group.TextBefore or ""); + WriteConstantTable(group.Constants, a_InheritedName or a_ClassAPI.Name); + cf:write(group.TextAfter or "", "</a></p>"); + end end - cf:write(" </table>\n\n"); end local function WriteVariables(a_Variables, a_InheritedName) @@ -833,11 +901,11 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI) local HasInheritance = ((#a_ClassAPI.Descendants > 0) or (a_ClassAPI.Inherits ~= nil)); - local HasConstants = (#a_ClassAPI.Constants > 0); + local HasConstants = (#a_ClassAPI.Constants > 0) or (a_ClassAPI.NumConstantsInGroups > 0); local HasFunctions = (#a_ClassAPI.Functions > 0); local HasVariables = (#a_ClassAPI.Variables > 0); for idx, cls in ipairs(InheritanceChain) do - HasConstants = HasConstants or (#cls.Constants > 0); + HasConstants = HasConstants or (#cls.Constants > 0) or (cls.NumConstantsInGroupsForDescendants > 0); HasFunctions = HasFunctions or (#cls.Functions > 0); HasVariables = HasVariables or (#cls.Variables > 0); end @@ -890,10 +958,10 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI) -- Write the constants: if (HasConstants) then cf:write(" <a name=\"constants\"><hr /><h1>Constants</h1></a>\n"); - WriteConstants(a_ClassAPI.Constants, nil); - g_Stats.NumTotalConstants = g_Stats.NumTotalConstants + #a_ClassAPI.Constants; + WriteConstants(a_ClassAPI.Constants, a_ClassAPI.ConstantGroups, a_ClassAPI.NumConstantsInGroups, nil); + g_Stats.NumTotalConstants = g_Stats.NumTotalConstants + #a_ClassAPI.Constants + (a_ClassAPI.NumConstantsInGroups or 0); for i, cls in ipairs(InheritanceChain) do - WriteConstants(cls.Constants, cls.Name); + WriteConstants(cls.Constants, cls.ConstantGroups, cls.NumConstantsInGroupsForDescendants, cls.Name); end; end; @@ -1180,7 +1248,7 @@ end function WriteStats(f) local function ExportMeter(a_Percent) local Color; - if (a_Percent > 95) then + if (a_Percent > 99) then Color = "green"; elseif (a_Percent > 50) then Color = "orange"; |