Module:Documentation/Module

local p = {} local h = {}

local i18n = require("Module:I18n") local s = i18n.getString local tab2 = require("Module:Tab2") local utilsMarkup = require("Module:UtilsMarkup") local utilsSchema = require("Module:UtilsSchema") local utilsString = require("Module:UtilsString") local utilsTable = require("Module:UtilsTable")

local MAX_ARGS_LENGTH = 50

function getModule(frame) local docPage = mw.title.new(frame:getParent:getTitle) local modulePage = docPage.basePageTitle local subpageText = modulePage.subpageText if subpageText == "Data" then modulePage = modulePage.basePageTitle end local module = require(frame.args.module or modulePage.fullText) return module, subpageText end

function p.Schema(frame) local module, subpageName = getModule(frame) local schemaName = frame.args[1] or subpageName local schemaDoc = p.schema(module.Schemas[schemaName], schemaName) return schemaDoc end

function p.Module(frame) local module, subpageName = getModule(frame) local categories = utilsMarkup.categories(h.getCategories(frame.args.type)) if subpageName == "Data" and type(module.Data) == "function" then return module.Data(frame) .. categories end if module.Documentation then return p.moduleDoc(module, module.Documentation, module.Schemas, 2) .. categories end return categories end

function p.schema(schema, schemaName) local definitions = utilsSchema.getTypeDefinitions(schema, schemaName or "", function(keyDef)		local key = keyDef.key		local symbolicType = keyDef.symbolicType		local rawType = keyDef.rawType		local typeLabel = keyDef.typeLabel		local desc = keyDef.desc		local subkeys = keyDef.subkeys		local parentType = keyDef.parentType		local isSubschema = keyDef.isSubschema		if schemaName == "..." and not parentType then			symbolicType = "vararg" .. symbolicType		end		symbolicType = mw.text.nowiki(symbolicType)		if subkeys and subkeys.allOf then			subkeys = utilsTable.concat(subkeys, utilsTable.flatten(subkeys.allOf))			subkeys.allOf = nil		end		if isSubschema then			if not desc and not subkeys then				return nil			end			local definition = utilsTable.flatten(subkeys or {})			if desc then				table.insert(definition, 1, {nil, desc})			end			return 		end		if subkeys and subkeys.oneOf and #subkeys.oneOf > 0 then local tabs = utilsTable.uniqueBy("tabContent")(utilsTable.flatten(subkeys.oneOf)) if #tabs == 1 then subkeys = utilsTable.concat(subkeys, tabs[1].tabContent) else subkeys = utilsTable.concat({tostring(tab2.Main(utilsTable.flatten(tabs), 1, "top"))}, subkeys) end subkeys.oneOf = nil end

if key and key ~= "" then key = tostring(mw.html.create("span")				:css("color", "#f8f8f2")				:wikitext(utilsMarkup.code(key))			) key = utilsMarkup.link("Module:Documentation/Documentation#Schemas", key) local type = typeLabel or symbolicType key = utilsMarkup.tooltip(key, utilsMarkup.code(type)) end definition = {key} if desc then table.insert(definition, desc) end if subkeys then definition = utilsTable.concat(definition, subkeys) end if parentType == utilsSchema.TYPES.record then definition = {definition} end return definition end)	if not schemaName then		definitions = utilsTable.flatten(utilsTable.tail(definitions))		definitions = 	else		definitions = {definitions}	end	local definitionsList = utilsMarkup.definitionList(definitions)	return definitionsList end

function p.moduleDoc(module, doc, schemas, headerLevel) utilsSchema.validate(p.Schemas.Documentation, "Documentation", doc, "p.Documentation") local output = "" if headerLevel == 2 then output = "\n" end for _, functionDoc in ipairs(doc) do		local paramSchemas = schemas and schemas[functionDoc.name] functionDoc = h.resolveFunctionDoc(functionDoc, paramSchemas) output = output .. utilsMarkup.heading(headerLevel)(functionDoc.name) .. "\n" if functionDoc.wip then output = output .. frame:expandTemplate({title = "UC"}) .. "\n" end output = output .. h.printFunctionSyntax(functionDoc) output = output .. h.printFunctionDescription(functionDoc) output = output .. h.printParamsDescription(functionDoc) output = output .. h.printReturnsDescription(functionDoc.returns) output = output .. h.printFunctionCases(module[functionDoc.name], functionDoc) end if doc.sections then for _, section in ipairs(doc.sections) do output = output .. ("==%s=="):format(section.heading) .. "\n" output = output .. p.moduleDoc(module, section.doc, schemas, headerLevel + 1) .. "\n" end end return output end

function h.resolveFunctionDoc(functionDoc, paramSchemas) paramSchemas = paramSchemas or {} functionDoc.cases = functionDoc.cases or {} if not functionDoc.order then functionDoc.order = 1 functionDoc.params = {functionDoc.params} for _, case in ipairs(functionDoc.cases) do			case.args = {case.args} end end for _, paramsList in ipairs(functionDoc.params) do		for i, param in ipairs(paramsList) do			paramsList[i] = { name = param, schema = paramSchemas[param] } end end if type(functionDoc.returns) ~= "table" then functionDoc.returns = {functionDoc.returns} for i, case in ipairs(functionDoc.cases) do			case.expect = {case.expect} end end return functionDoc end

function h.printFunctionSyntax(functionDoc) local result = functionDoc.name for _, params in ipairs(functionDoc.params) do result = result .. "(" .. h.printParamsSyntax(params) .. ")" end return utilsMarkup.code(result) .. "\n" end function h.printParamsSyntax(params) local paramsSyntax = {} for _, param in ipairs(params or {}) do		local paramSyntax = param.name if param.schema and not param.schema.required then paramSyntax = "[" .. paramSyntax .. "]"		end table.insert(paramsSyntax, paramSyntax) end return table.concat(paramsSyntax, ", ") end

function h.printFunctionDescription(functionDoc) local lines = {} if functionDoc.order > 1 then table.insert(lines, utilsMarkup.italic(s("higherOrder"))) end if functionDoc.desc then table.insert(lines, mw.getCurrentFrame:preprocess(functionDoc.desc)) end local result = table.concat(lines, "\n\n") if #result > 0 then result = "\n" .. result .. "\n" end return result end

function h.printParamsDescription(functionDoc) if not functionDoc.params or #functionDoc.params == 0 then return "" end local allParams = utilsTable.flatten(functionDoc.params) local paramDefinitions = {} for _, param in ipairs(allParams) do		if param.schema then table.insert(paramDefinitions, p.schema(param.schema, param.name)) end end if #paramDefinitions == 0 then return "" end local paramList = utilsMarkup.list(paramDefinitions) local heading = ";" .. s("headers.parameters") .. "\n" return heading .. paramList end

function h.printReturnsDescription(returns) if not returns or #returns == 0 then return "" end local returnsList = utilsMarkup.bulletList(returns) local heading = "\n;" .. s("headers.returns") .. "\n" local result = heading .. mw.getCurrentFrame:preprocess(returnsList) return result end

function h.printFunctionCases(fn, doc) if not doc.cases or #doc.cases == 0 then return "" end local result = "\n;" .. s("headers.examples") .. "\n" local inputColumn = s("headers.input") local outputColumn = s("headers.output") local resultColumn = s("headers.result") local statusColumn = utilsMarkup.tooltip(s("headers.status"), s("explainStatusColumn")) local headerCells = utilsTable.compactNils({		inputColumn, 		not doc.cases.resultOnly and outputColumn or nil, 		not doc.cases.outputOnly and resultColumn or nil, 		statusColumn,	}) local tableData = { hideEmptyColumns = true, rows = { {				header = true, cells = headerCells, }		},	}	for _, case in ipairs(doc.cases) do		local caseRows = h.case(fn, doc, case, doc.cases) tableData.rows = utilsTable.concat(tableData.rows, caseRows) end result = result .. utilsMarkup.wikitable(tableData) .. "\n" return result end

function h.case(fn, doc, case, options) local rows = {} local input = h.printInput(doc, case.args) local outputs = h.evaluateFunction(fn, doc, case.args) local expected = case.expect or {} for i = 1, #doc.returns do		local outputData, resultData, statusData = h.evaluateOutput(outputs[i], expected[i]) table.insert(rows, utilsTable.compactNils({ not options.resultOnly and outputData or nil, not options.outputOnly and resultData or nil, statusData }))	end table.insert(rows[1], 1, {		content = input,		rowspan = #doc.returns,	}) if case.desc then table.insert(rows, 1, {			{				header = true,				colspan = -1,				styles = {					["text-align"] = "left"				},				content = case.desc,			}		}) end return rows end

function h.printInput(doc, argsList) local result = doc.name local allArgs = utilsTable.flatten(argsList) local lineWrap = #allArgs == 1 and type(allArgs[1]) == "string" for i, args in ipairs(argsList) do result = result .. "(" .. h.printInputArgs(args, doc.params[i], lineWrap) .. ")" end return utilsMarkup.lua(result, {		wrapLines = lineWrap	}) end function h.printInputArgs(args, params) args = args or {} local argsText = {} for i = 1, math.max(#params, #args) do		local argText = args[i] and utilsTable.print(args[i]) or "nil" if not (#args == 1 and type(args[i]) == "table") then argText = string.gsub(argText, "\n", "\n ") --ensures proper indentation of multiline table args end table.insert(argsText, argText) end -- Trim nil arguments off the end so long as they're optional (but keep the first one). local argsText = utilsTable.dropRightWhile(function(argText, i)		return i > 1 and argText == "nil" and params[i] and params[i].schema and not params[i].schema.required	end)(argsText) local result = table.concat(argsText, ", ") local lines = mw.text.split(result, "\n") -- print multiline if there's multiple args with at least one table or a line longer than the max length if #args > 1 and (#lines > 1 or #lines[1] > MAX_ARGS_LENGTH) then result = "\n " .. table.concat(argsText, ",\n ") .. "\n" end return result end

function h.evaluateFunction(fn, doc, args) local order = doc.order for i = 1, order - 1 do		fn = fn(unpack(args[i])) end return {fn(unpack(args[order]))} end

function h.evaluateOutput(output, expected) local formattedOutput = h.formatValue(output) local outputData = formattedOutput local resultData = "" if type(output) == "string" then resultData = utilsMarkup.killBacklinks(output) resultData, categories = utilsMarkup.stripCategories(output) if (#categories > 0) then local categoryList = utilsMarkup.bold(s('headers.categoriesAdded')) .. utilsMarkup.bulletList(categories) resultData = { {resultData}, {categoryList}, }		end end if type(expected) == "string" then expected = string.gsub(expected, "\t", "") end local passed = utilsTable.isEqual(expected)(output) local statusData = (expected ~= nil or output == nil) and h.printStatus(passed) or nil if statusData and not passed then local expectedOutput = h.formatValue(expected) outputData = utilsMarkup.wikitable({			hideEmptyColumns = true,			styles = { width = "100%" },			rows = {				{ 					{ 						header = true, 						content = "Expected", 						styles = { width = "1em"}, -- "shrink-wraps" this column					}, 					{ content = expectedOutput },				},				{					{ header = true, content = "Actual" }, 					{ content = formattedOutput },				},			}		}) end return outputData, resultData, statusData end

function h.formatValue(val) if type(val) == "string" then val = string.gsub(val, "&#", "&#38;#") -- show entity codes return utilsMarkup.pre(string.gsub(utilsTable.print(val), "\n", "\\n\n")) -- Show newlines end return utilsMarkup.lua(val) end

function h.printStatus(success) local img = success and "" or "" local msg = success and s("explainStatusGood") or s("explainStatusBad") img = utilsMarkup.tooltip(img, msg) local cat = success and "" or utilsMarkup.category(s("failingTestsCategory")) return img .. cat end

function h.getCategories(type) local title = mw.title.getCurrentTitle local isDoc = title.subpageText == "Documentation" local moduleTitle = (isDoc or isData) and mw.title.new(title.baseText) or title local isData = moduleTitle.subpageText == "Data" local isUtil = utilsString.startsWith("Utils", moduleTitle.text) local isSubmodule = moduleTitle.subpageText ~= moduleTitle.text if type == "submodule" then isSubmodule = true end

if isDoc and isData then return {s("cat.dataDoc")} end if isDoc and isSubmodule then return {s("cat.submoduleDoc")} end if isDoc then return {s("cat.moduleDoc")} end if isData then return {s("cat.data")} end if isSubmodule then return {s("cat.submodules")} end if isUtil then return {s("cat.modules"), s("cat.utilityModules")} end

return {s("cat.modules")} end

i18n.loadStrings({	en = {		higherOrder = "This is a higher-order function.",		failingTestsCategory = "Category:Modules with failing tests",		explainStatusColumn = "Indicates whether a feature is working as expected",		explainStatusGood = "This feature is working as expected",		explainStatusBad = "This feature is not working as expected",		headers = {			parameters = "Parameters",			returns = "Returns",			examples = "Examples",			input = "Input",			output = "Output",			result = "Result",			categories = "Categories",			categoriesAdded = "Categories added",			status = "Status",		},		cat = {			modules = "Category:Modules",			submodules = "Category:Submodules",			utilityModules = "Category:Utility Modules",			moduleDoc = "Category:Module Documentation",			submoduleDoc = "Category:Submodule Documentation",			data = "Category:Module Data",			dataDoc = "Category:Module Data Documentation", }	} })

p.Schemas = { Documentation = { desc = "Either an array of function docs, or an array of sections of function docs.", oneOf = { { _ref = "#/definitions/functions" }, { _ref = "#/definitions/sections" }, },		definitions = { functions = { type = "array", items = { type = "record", properties = { { 							name = "name", type = "string", required = true, desc = "The name of a function in the module.", },						{							name = "desc", type = "string", desc = "Description of the function. Use only when clarification is needed—usually the param/returns/cases doc speaks for itself.", },						{							name = "order", type = "number", desc = "An integer representing the arity of a higher-order function.  is order 1,   is order 2, and so on.", default = 1, },						{							name = "params", required = true, type = "array", items = { desc = "An array of parameter names, or an array of arrays if the function has  > 1. Integrates with Module:Schema.", oneOf = { { type = "string" }, { type = "array", items = { type = "string" } } },							},						},						{							name = "returns", desc = "A string describing the return value of the function, or an array of such strings if the function returns multiple values", oneOf = { { type = "string" }, { type = "array", items = { type = "string" } }, },						},						{							name = "cases", desc = "A collection of use cases that double as test cases, plus a couple flags.", allOf = { {									type = "record", properties = { {											name = "resultOnly", type = "boolean", desc = "When, displays only rendered wikitext as opposed to raw function output. Useful for functions returning strings of complex wikitext.", },										{											name = "outputOnly", type = "boolean", desc = "When, displays only the raw output of the function (opposite of  ). Enabled by default for functions returning data of type other than  ." },									},								},								{									type = "array", items = { type = "record", properties = { {												name = "desc", type = "string", desc = "A description of the use case.", },											{												name = "args", type = "array", items = { type = "any" }, desc = "An array of arguments to pass to the function, or an array of arrays if the function has  > 1", },											{												name = "expect", type = "any", desc = "The expected return value, which is deep-compared against the actual value to determine pass/fail status. Or, an array of such items if there are multiple return values.", },										},									},								}							},						},						{							name = "wip", type = "boolean", desc = "Tags the function doc with Template:UC." }					},				},			},			sections = { type = "record", additionalProperties = true, properties = { {						name = "sections", required = true, type = "array", items = { type = "record", properties = { {									name = "heading", required = true, type = "string", desc = "Heading for the documentation section.", },								{									name = "doc", _ref = "#/definitions/functions", required = true, _hideSubkeys = true, desc = "An array of tables describing functions (see above).", },							},						},					},				},			},		}	}, }

return p