Module:module documentation

---

පහත දැක්වෙන උපදෙස්, Module:module documentation/documentation හි පිහිටා ඇත. Module:module documentation/documentation]]. ^{[සංස්කරණය]}

ප්‍රයෝජනවත් සබැඳි: උප පිටු ලැයිස්තුව • සබැඳි • transclusions • testcases • sandbox

This module provides automatically generated documentation for other modules. It fetches inline comments in Lua code and convert them to a documentation page, or a section of it.

In fact, it is also generating a documentation for itself. You can see the code below and get a living example.

export.show

function export.show(frame)

Generates the documentation wikitext from the Lua code. It can take 3 template arguments.

• |comment_level=: How many equal signs the comment to be fetched uses in its bracket. Defaults to 2.

  E.g. 3 means --[===[ ... (comment block) ]===].

• |section_level=: The level of the section each function's text will occupy. Defaults to 2 (L2).
• |identifier=: A Lua string pattern. Only the comments of functions whose names can be matched by this pattern is used. When it is not given, all function are accepted.

Usage notes

• All local functions will be ignored, since they are invisible outside the module.
• Curly brackets in comments are used as a shortcut for syntaxhighlight. Use syntaxhighlight instead for whatever reason making it fail.

--[==[
This module provides automatically generated documentation for other modules. It fetches inline comments in Lua code and convert them to a documentation page, or a section of it.
In fact, it is also generating a documentation for itself. You can see the code below and get a living example.
]==]
local export = {}

local function format_doc(str)
	return (str
		:gsub('%f[\n,{]\n%f[^\n*#:;]', '\n\n') -- wiki newlines
		:gsub('(\n[ *#:]*)(|?[_%w]+=?):', '%1<code><b>%2</b></code>:') -- parameter names
		:gsub('%b{}', function(m0) -- {} blocks
			if m0:sub(2, 2) == '{' and m0:sub(-2, -2) == '}' then return nil end
			return '<syntaxhighlight lang=lua' .. (m0:match'\n' and '' or ' inline') .. '>' .. m0:sub(2, -2) .. '</syntaxhighlight>'
		end))
end

--[==[
Generates the documentation wikitext from the Lua code. It can take 3 template arguments.
* |comment_level=: How many equal signs the comment to be fetched uses in its bracket. Defaults to 2.
*: E.g. 3 means {--[===[ ... (comment block) ]===]}.
* |section_level=: The level of the section each function's text will occupy. Defaults to 2 (L2).
* |identifier=: A Lua string pattern. Only the comments of functions whose names can be matched by this pattern is used. When it is not given, all function are accepted.
]==]
function export.show(frame)
	local args = frame:getParent().args or {}
	
	local comment_level = tonumber(args['comment_level']) or 2
	local pattern_comment = '%-%-%[' .. ('='):rep(comment_level) .. '%[\n?(.-)\n?]' .. ('='):rep(comment_level) .. ']()'
	local section_mark = ('='):rep(tonumber(args['section_level']) or 2)
	local pattern_identifier = args['identifier'] or ''
	
	local mod_title = mw.title.getCurrentTitle()
	if mod_title.text:match'/documentation$' then return '(<i>The generated documentation is located at the module page.</i>)' end
	local mod_text = mod_title:getContent()
	if not mod_text then return '(<i>The module page does not exist now.</i>)' end
	
	local chunk
	
	local leading_section_raw = mod_text:match('^' .. pattern_comment)
	if leading_section_raw then
		chunk = { format_doc(leading_section_raw) }
	else chunk = {} end
	
	for p0, f, fn in mod_text:gmatch('()\nfunction +(([^\n(]+)[^\n)]+%))') do
		if fn:match(pattern_identifier) then			
			local c = mod_text:sub(1, p0 - 1):match('^.*' .. pattern_comment .. '%s*$')
			table.insert(chunk, section_mark .. fn .. section_mark .. '\n\n' .. '<syntaxhighlight lang=lua inline>function ' .. f .. '</syntaxhighlight>\n\n' .. format_doc(c or '<strong class="error">This function lacks a documentation. Please add a description of its usages, inputs and outputs, or its difference from similar functions, or make it local to remove it from the function list.</strong>[[Category:Templates and modules needing documentation]]'))
		end
	end
	
	local postscriptum = mod_text:match('^.*' .. pattern_comment .. '%s*$')
	if postscriptum then
		table.insert(chunk, section_mark .. 'Usage notes' .. section_mark .. '\n\n' .. format_doc(postscriptum))
	end
	
	return frame:preprocess(table.concat(chunk, '\n\n'))
end

return export
--[==[
* All local functions will be ignored, since they are invisible outside the module.
* Curly brackets in comments are used as a shortcut for syntaxhighlight. Use syntaxhighlight instead for whatever reason making it fail.
]==]