From f53cf5d13091ad9df3ea17823b2f7d1ca5ef6167 Mon Sep 17 00:00:00 2001 From: Lukas Pioch Date: Thu, 3 Aug 2017 15:40:40 +0200 Subject: APIDump: Class types in variables and hooks are now linkified (#3892) --- Server/Plugins/APIDump/main_APIDump.lua | 41 ++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/Server/Plugins/APIDump/main_APIDump.lua b/Server/Plugins/APIDump/main_APIDump.lua index 2c88846e7..0f1476ef7 100644 --- a/Server/Plugins/APIDump/main_APIDump.lua +++ b/Server/Plugins/APIDump/main_APIDump.lua @@ -206,10 +206,15 @@ end -- Make a link out of anything with the special linkifying syntax {{link|title}} -local function LinkifyString(a_String, a_Referrer) +local function LinkifyString(a_String, a_Referrer, a_API) assert(a_Referrer ~= nil); assert(a_Referrer ~= ""); + -- If the string is a known class, return a direct link to it: + if (a_API[a_String]) then + return "" .. a_String .. "" + end + --- Adds a page to the list of tracked pages (to be checked for existence at the end) local function AddTrackedPage(a_PageName) local Pg = (g_TrackedPages[a_PageName] or {}); @@ -259,7 +264,7 @@ end -local function WriteHtmlHook(a_Hook, a_HookNav) +local function WriteHtmlHook(a_Hook, a_HookNav, a_API) local fnam = "API/" .. a_Hook.DefaultFnName .. ".html"; local f, error = io.open(fnam, "w"); if (f == nil) then @@ -295,7 +300,7 @@ local function WriteHtmlHook(a_Hook, a_HookNav) f:write([[

]]); - f:write(LinkifyString(a_Hook.Desc, HookName)); + f:write(LinkifyString(a_Hook.Desc, HookName, a_API)); f:write("

\n

Callback function

\n

The default name for the callback function is "); f:write(a_Hook.DefaultFnName, ". It has the following signature:\n"); f:write("

function My", HookName, "(");
@@ -310,9 +315,9 @@ local function WriteHtmlHook(a_Hook, a_HookNav)
 	end
 	f:write(")
\n

Parameters:

\n\n"); for _, param in ipairs(a_Hook.Params) do - f:write("\n"); + f:write("\n"); end - f:write("
NameTypeNotes
", param.Name, "", LinkifyString(param.Type, HookName), "", LinkifyString(param.Notes, HookName), "
", param.Name, "", LinkifyString(param.Type, HookName, a_API), "", LinkifyString(param.Notes, HookName, a_API), "
\n

" .. LinkifyString(a_Hook.Returns or "", HookName) .. "

\n\n"); + f:write("\n

" .. LinkifyString(a_Hook.Returns or "", HookName, a_API) .. "

\n\n"); f:write([[

Code examples

Registering the callback

]]); f:write("
\n");
 	f:write([[cPluginManager:AddHook(cPluginManager.]] .. a_Hook.Name .. ", My" .. a_Hook.DefaultFnName .. [[);]]);
@@ -354,7 +359,7 @@ end
 -- a_Hooks is an array of hook descriptions
 -- a_UndocumentedHooks is a table that will be filled with the names of hooks that are not documented
 -- a_HookNav is the HTML code for the menu on the left that is constant for all hook pages
-local function WriteHooks(f, a_Hooks, a_UndocumentedHooks, a_HookNav)
+local function WriteHooks(f, a_Hooks, a_UndocumentedHooks, a_HookNav, a_API)
 	f:write([[
 		
Hooks

 		

@@ -379,8 +384,8 @@ local function WriteHooks(f, a_Hooks, a_UndocumentedHooks, a_HookNav)
 			f:write("				\n					" .. hook.Name .. "\n					(No documentation yet)\n 				\n");
 			table.insert(a_UndocumentedHooks, hook.Name);
 		else
-			f:write("				\n					" .. hook.Name .. "\n					" .. LinkifyString(hook.CalledWhen, hook.Name) .. "\n				\n");
-			WriteHtmlHook(hook, a_HookNav);
+			f:write("				\n					" .. hook.Name .. "\n					" .. LinkifyString(hook.CalledWhen, hook.Name, a_API) .. "\n				\n");
+			WriteHtmlHook(hook, a_HookNav, a_API);
 		end
 	end
 	f:write([[
@@ -814,7 +819,7 @@ local function CreateFunctionParamsDescription(a_FnParams, a_ClassName, a_API)
 
 	-- If the params description is a string (old format), just linkify it:
 	if (pt == "string") then
-		return LinkifyString(a_FnParams, a_ClassName)
+		return LinkifyString(a_FnParams, a_ClassName, a_API)
 	end
 
 	-- If the params description is an empty table, give no description at all:
@@ -881,7 +886,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API)
 			cf:write("", func.Name, "\n");
 			cf:write("", CreateFunctionParamsDescription(func.Params or {}, a_InheritedName or a_ClassAPI.Name, a_API), "\n");
 			cf:write("", CreateFunctionParamsDescription(func.Returns or {}, a_InheritedName or a_ClassAPI.Name, a_API), "\n");
-			cf:write("", StaticClause .. LinkifyString(func.Notes or "(undocumented)", (a_InheritedName or a_ClassAPI.Name)), "\n");
+			cf:write("", StaticClause .. LinkifyString(func.Notes or "(undocumented)", (a_InheritedName or a_ClassAPI.Name), a_API), "\n");
 		end
 		cf:write("\n");
 	end
@@ -891,7 +896,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API)
 		for _, cons in ipairs(a_Constants) do
 			cf:write("", cons.Name, "\n");
 			cf:write("", cons.Value, "\n");
-			cf:write("", LinkifyString(cons.Notes or "", a_Source), "\n");
+			cf:write("", LinkifyString(cons.Notes or "", a_Source, a_API), "\n");
 		end
 		cf:write("\n\n");
 	end
@@ -914,9 +919,9 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API)
 		for _, group in pairs(a_ConstantGroups) do
 			if ((a_InheritedName == nil) or group.ShowInDescendants) then
 				cf:write("
");
-				cf:write(LinkifyString(group.TextBefore or "", Source));
+				cf:write(LinkifyString(group.TextBefore or "", Source, a_API));
 				WriteConstantTable(group.Constants, a_InheritedName or a_ClassAPI.Name);
-				cf:write(LinkifyString(group.TextAfter or "", Source), "
");
+				cf:write(LinkifyString(group.TextAfter or "", Source, a_API), "
");
 			end
 		end
 	end
@@ -933,8 +938,8 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API)
 		cf:write("\n");
 		for _, var in ipairs(a_Variables) do
 			cf:write("\n");
-			cf:write("\n");
-			cf:write("\n				\n");
+			cf:write("\n");
+			cf:write("\n				\n");
 		end
 		cf:write("
NameTypeNotes
", var.Name, "", LinkifyString(var.Type or "(undocumented)", a_InheritedName or a_ClassAPI.Name), "", LinkifyString(var.Notes or "", a_InheritedName or a_ClassAPI.Name), "
", LinkifyString(var.Type or "(undocumented)", a_InheritedName or a_ClassAPI.Name, a_API), "", LinkifyString(var.Notes or "", a_InheritedName or a_ClassAPI.Name, a_API), "
\n\n");
 	end
@@ -1026,7 +1031,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API)
 	cf:write("
", ClassName, " class
\n");
 	if (a_ClassAPI.Desc ~= nil) then
 		cf:write("
");
-		cf:write(LinkifyString(a_ClassAPI.Desc, ClassName));
+		cf:write(LinkifyString(a_ClassAPI.Desc, ClassName, a_API));
 		cf:write("
\n\n");
 	end;
 
@@ -1081,7 +1086,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API)
 	if (a_ClassAPI.AdditionalInfo ~= nil) then
 		for i, additional in ipairs(a_ClassAPI.AdditionalInfo) do
 			cf:write("
", additional.Header, "
\n");
-			cf:write(LinkifyString(additional.Contents, ClassName));
+			cf:write(LinkifyString(additional.Contents, ClassName, a_API));
 		end
 	end
 
@@ -1464,7 +1469,7 @@ local function DumpAPIHtml(a_API, a_Descs)
 
 	WriteArticles(f, a_Descs);
 	WriteClasses(f, a_API, ClassMenu);
-	WriteHooks(f, Hooks, UndocumentedHooks, HookNav);
+	WriteHooks(f, Hooks, UndocumentedHooks, HookNav, a_API);
 
 	-- Copy the static files to the output folder:
 	local StaticFiles =
-- 
cgit v1.2.3