APIDump: Implemented basic hook documentation.
This commit is contained in:
parent
76d056e5f7
commit
9dafba5015
@ -2055,6 +2055,33 @@ World:ForEachEntity(
|
||||
},
|
||||
},
|
||||
|
||||
|
||||
Hooks =
|
||||
{
|
||||
HOOK_CHAT =
|
||||
{
|
||||
CalledWhen = "Player sends a chat message",
|
||||
DefaultFnName = "OnChat", -- also used as pagename
|
||||
Desc = [[
|
||||
A plugin may implement an OnChat() function and register it as a Hook to process chat messages from
|
||||
the players. The function is then called for every in-game message sent from any player. Note that
|
||||
commands are handled separately using a command framework API.
|
||||
]],
|
||||
Params = {
|
||||
{ Name = "Player", Type = "{{cPlayer}}", Notes = "The player who sent the message" },
|
||||
{ Name = "Message", Type = "string", Notes = "The message" },
|
||||
},
|
||||
Returns = [[
|
||||
The plugin may return 2 values. The first is a boolean specifying whether the hook handling is to be
|
||||
stopped or not. If it is false, the message is broadcast to all players in the world. If it is true,
|
||||
no message is broadcast and no further action is taken.</p>
|
||||
<p>
|
||||
The second value is specifies the message to broadcast. This way, plugins may modify the message. If
|
||||
the second value is not provided, the original message is used.
|
||||
]],
|
||||
}, -- HOOK_CHAT
|
||||
}, -- Hooks[]
|
||||
|
||||
|
||||
IgnoreClasses =
|
||||
{
|
||||
@ -2080,12 +2107,15 @@ World:ForEachEntity(
|
||||
"%a+.delete", -- AnyClass.delete
|
||||
|
||||
-- Functions global in the APIDump plugin:
|
||||
"Initialize",
|
||||
"DumpAPITxt",
|
||||
"CreateAPITables",
|
||||
"DumpAPIHtml",
|
||||
"DumpAPITxt",
|
||||
"Initialize",
|
||||
"LinkifyString",
|
||||
"ReadDescriptions",
|
||||
"ReadHooks",
|
||||
"WriteHtmlClass",
|
||||
"WriteHtmlHook",
|
||||
},
|
||||
|
||||
ExtraPages =
|
||||
|
@ -164,6 +164,8 @@ function DumpAPIHtml()
|
||||
LOG("Dumping all available functions and constants to API subfolder...");
|
||||
|
||||
local API, Globals = CreateAPITables();
|
||||
local Hooks = {};
|
||||
local UndocumentedHooks = {};
|
||||
|
||||
-- Sort the classes by name:
|
||||
table.sort(API,
|
||||
@ -176,8 +178,21 @@ function DumpAPIHtml()
|
||||
Globals.Name = "Globals";
|
||||
table.insert(API, Globals);
|
||||
|
||||
-- Extract hook constants:
|
||||
for name, obj in pairs(cPluginManager) do
|
||||
if (type(obj) == "number") and (name:match("HOOK_.*")) then
|
||||
table.insert(Hooks, { Name = name });
|
||||
end
|
||||
end
|
||||
table.sort(Hooks,
|
||||
function(Hook1, Hook2)
|
||||
return (Hook1.Name < Hook2.Name);
|
||||
end
|
||||
);
|
||||
|
||||
-- Read in the descriptions:
|
||||
ReadDescriptions(API);
|
||||
ReadHooks(Hooks);
|
||||
|
||||
-- Create the output folder
|
||||
if not(cFile:IsFolder("API")) then
|
||||
@ -220,7 +235,16 @@ function DumpAPIHtml()
|
||||
for the event). See each hook's details to see the exact behavior.</p>
|
||||
<table><tr><th>Hook name</th><th>Called when</th></tr>
|
||||
]]);
|
||||
-- TODO: Write out the hooks into a table
|
||||
for i, hook in ipairs(Hooks) do
|
||||
if (hook.DefaultFnName == nil) then
|
||||
-- The hook is not documented yet
|
||||
f:write("<tr><td>" .. hook.Name .. "</td><td><i>(No documentation yet)</i></td></tr>\n");
|
||||
table.insert(UndocumentedHooks, hook.Name);
|
||||
else
|
||||
f:write("<tr><td><a href=\"" .. hook.DefaultFnName .. ".html\">" .. hook.Name .. "</a></td><td>" .. hook.CalledWhen .. "</td></tr>\n");
|
||||
WriteHtmlHook(hook);
|
||||
end
|
||||
end
|
||||
f:write([[</table>
|
||||
<a name="extra"><h2>Extra pages</h2></a>
|
||||
<p>The following pages provide various extra information</p>
|
||||
@ -286,6 +310,24 @@ function DumpAPIHtml()
|
||||
f:write("\t\t},\n\n");
|
||||
end
|
||||
end -- for i, cls - API[]
|
||||
f:write("\t},\n");
|
||||
|
||||
if (#UndocumentedHooks > 0) then
|
||||
f:write("\n\tHooks =\n\t{\n");
|
||||
for i, hook in ipairs(UndocumentedHooks) do
|
||||
if (i > 1) then
|
||||
f:write("\n");
|
||||
end
|
||||
f:write("\t\t" .. hook .. " =\n\t\t{\n");
|
||||
f:write("\t\t\tCalledWhen = \"\",\n");
|
||||
f:write("\t\t\tDefaultFnName = \"On\", -- also used as pagename\n");
|
||||
f:write("\t\t\tDesc = [[]],\n");
|
||||
f:write("\t\t\tParams =\n\t\t\t{\n");
|
||||
f:write("\t\t\t\t{ Name = \"\", Type = \"\", Notes = \"\" },\n\t\t\t},\n");
|
||||
f:write("\t\t\tReturns = [[]],\n");
|
||||
f:write("\t\t}, -- " .. hook .. "\n");
|
||||
end
|
||||
end
|
||||
f:close();
|
||||
end
|
||||
|
||||
@ -531,19 +573,46 @@ end
|
||||
|
||||
|
||||
|
||||
function ReadHooks(a_Hooks)
|
||||
--[[
|
||||
a_Hooks = {
|
||||
{ Name = "HOOK_1"},
|
||||
{ Name = "HOOK_2"},
|
||||
...
|
||||
};
|
||||
We want to add hook descriptions to each hook in this array
|
||||
--]]
|
||||
for i, hook in ipairs(a_Hooks) do
|
||||
local HookDesc = g_APIDesc.Hooks[hook.Name];
|
||||
if (HookDesc ~= nil) then
|
||||
for key, val in pairs(HookDesc) do
|
||||
hook[key] = val;
|
||||
end
|
||||
end
|
||||
end -- for i, hook - a_Hooks[]
|
||||
end
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
-- Make a link out of anything with the special linkifying syntax {{link|title}}
|
||||
function LinkifyString(a_String)
|
||||
local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", "<a href=\"%1.html\">%2</a>") -- {{link|title}}
|
||||
txt = txt:gsub("{{([^|}]*)}}", "<a href=\"%1.html\">%1</a>") -- {{LinkAndTitle}}
|
||||
return txt;
|
||||
end
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
function WriteHtmlClass(a_ClassAPI, a_AllAPI)
|
||||
local cf, err = io.open("API/" .. a_ClassAPI.Name .. ".html", "w");
|
||||
if (cf == nil) then
|
||||
return;
|
||||
end
|
||||
|
||||
-- Make a link out of anything with the special linkifying syntax {{link|title}}
|
||||
local function LinkifyString(a_String)
|
||||
local txt = a_String:gsub("{{([^|}]*)|([^}]*)}}", "<a href=\"%1.html\">%2</a>") -- {{link|title}}
|
||||
txt = txt:gsub("{{([^|}]*)}}", "<a href=\"%1.html\">%1</a>") -- {{LinkAndTitle}}
|
||||
return txt;
|
||||
end
|
||||
|
||||
-- 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
|
||||
@ -584,7 +653,7 @@ function WriteHtmlClass(a_ClassAPI, a_AllAPI)
|
||||
CurrInheritance = CurrInheritance.Inherits;
|
||||
end
|
||||
|
||||
cf:write([[<html><head><title>MCServer API - ]] .. a_ClassAPI.Name .. [[</title>
|
||||
cf:write([[<html><head><title>MCServer API - ]] .. a_ClassAPI.Name .. [[ class</title>
|
||||
<link rel="stylesheet" type="text/css" href="main.css" />
|
||||
</head><body>
|
||||
<h1>Contents</h1>
|
||||
@ -664,3 +733,45 @@ end
|
||||
|
||||
|
||||
|
||||
function WriteHtmlHook(a_Hook)
|
||||
local fnam = "API/" .. a_Hook.DefaultFnName .. ".html";
|
||||
local f, error = io.open(fnam, "w");
|
||||
if (f == nil) then
|
||||
LOG("Cannot write \"" .. fnam .. "\": \"" .. error .. "\".");
|
||||
return;
|
||||
end
|
||||
f:write([[<html><head><title>MCServer API - ]] .. a_Hook.DefaultFnName .. [[ hook</title>
|
||||
<link rel="stylesheet" type="text/css" href="main.css" />
|
||||
</head><body>
|
||||
<h1>]] .. a_Hook.Name .. [[ hook</h1>
|
||||
<p>
|
||||
]]);
|
||||
f:write(LinkifyString(a_Hook.Desc));
|
||||
f:write("</p><h1>Callback function</h1><pre>function " .. a_Hook.DefaultFnName .. "(");
|
||||
if (a_Hook.Params == nil) then
|
||||
a_Hook.Params = {};
|
||||
end
|
||||
for i, param in ipairs(a_Hook.Params) do
|
||||
if (i > 1) then
|
||||
f:write(", ");
|
||||
end
|
||||
f:write(param.Name);
|
||||
end
|
||||
f:write(")</pre><p>Parameters:\n<table><tr><th>Name</th><th>Type</th><th>Notes</th></tr>\n");
|
||||
for i, param in ipairs(a_Hook.Params) do
|
||||
f:write("<tr><td>" .. param.Name .. "</td><td>" .. LinkifyString(param.Type) .. "</td><td>" .. LinkifyString(param.Notes) .. "</td></tr>\n");
|
||||
end
|
||||
f:write("</table></p>\n<p>" .. (a_Hook.Returns or "") .. "</p>\n");
|
||||
f:write([[<h1>Code examples</h1>
|
||||
<h2>Registering the callback</h2>
|
||||
<pre>
|
||||
cPluginManager.AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);
|
||||
</pre>
|
||||
]]);
|
||||
-- TODO: Other code examples
|
||||
f:close();
|
||||
end
|
||||
|
||||
|
||||
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user