Module:Sandbox/Jeblad/LuaDoc

Module documentation[view] [edit] [history] [purge]

Usage

Usual call for documentation of a single module, like a replacement for the usual documentation page, would be like this

{{#invoke:LuaDoc|build|{{FULLPAGENAME}}}}

In the actual code there will be specially formatted comments. All comments acted upon by this use a single line comment followed by an at sign (@) and a tag name. (Is there any reason why we should use other kinds of comments? They are useful for commenting out blocks? How to describe local functions? Should inline docs be used, those can be supported by wikitext?)

Note that all text is processed as wikitext, and it is possible to link internally and externally as seems fit. This also creates some problems as part of the text will have spaces or page breaks in odd places.

A summary-line is prefixed by three (3) hyphens (dashes), and double as a marker for the place where the code is to be divided into chunks. The stuff in each chunk is processed separately. The summary will be marked as such, and it will be possible to use it as a fragment identifier.

A tag is prefixed by two (2) hyphens (dashes), optional spaces, a single at-sign (@) and a tag name. The following text can be further split and given special markup.

A single line comment following a summary or tag will be joined with the preceding line. If the line contains text it will be joined with a dividing space, if it is empty it will add a newline. The newline can be further processed and given special markup.

Recognized tags can be removed from the document flow or left in place, as seems fit for the processed chunk of text. Those removed from the document can be added to separate lists for separate processing or rejected altogether.

Unrecognized tags will be rendered in place with a generic mechanism.

All tags with a leading x- will be rejected, no matter if they can be recognized or not.

Available tags

A series of different tags are recognized. They capture words or other constructs, and will process the captures specially. The captures will be formatted and linked as necessary. The remaining text is treated as ordinary wikitext.

If a tag taking captures fails to detect a capture, then possible captures will be successively pushed out, ultimately pushing all possible captures into the following text. This can be used in some cases to avoid using a specific capture, but is an indication that the documentation is broken.

It is the intention to support the listed tags, but others can be added later. The block tags from JSdoc could be a source for additional entries.

@author^*

Identify the author of an item. Authors are those that have contributed with content to the item.

@copyright^*

Document some copyright information. Copyright is an identification of the entity that is allowed to set the license.

@license^*

Identify the license that applies to this code. The license is the document that says why a module can be reused.

@provenance^*

Document the history of ownership for the module. Link this to the external source if suitable.

@release^? (alt @version)

Identify the release or version number of an item. This is necessary for imported modules.

@since^? [date|version|revision]

Document when this feature was added. The date, version, or revision when some functionality was added.

@deprecated^? [date|version|revision]

Document when this feature was deprecated. The date, version, or revision is when some functionality become deprecated.

@var^? [word|descriptor]

Describe a variable definition. First field is a type declaration. This implies a variable-class. (Not sure about this one, its like the signature of the function.)

@field^* [word|descriptor]

Describe a table field definition. First field is a type declaration. This implies a variable-class.

@param^* [word|descriptor] (alt @arg, @argument)

Document the parameter to a function. First field is a type declaration. This implies a function-class.

@returns^* (alt @return)

Document the return values of a function. Since Lua can return multiple values, this tag could appear more than once. This implies a function-class.

@see^*

Refer to some other documentation for more information. This tag spawns an entry possibly with links in a navigation box.

@usage <text>

Describe the usage of the function or variable. This is one of several such free sections. The tag will be localized as necessary. (Not sure about this one, perhaps name the individual modifiers.)

• ^* Zero or more entries
• ⁺ One or more entries
• ^? Zero or one entry

Inferred tags

Some tags will be extracted from the following block of code if missing (it is the intention to support these)

@class <word>

The first documentation block will be assumed to be of class module, and later ones will have classes inferred from the code block unless it is specified explicitly.

@description <text>

The description is the documentation following the summary, but can be set explicitly. (Not sure if this should be described here, and if it should have a tag.)

@name <word>

The name of the function or table definition. This is usually inferred from simple code analysis, and the programmer does not need to define it. (The programmer should not add it at all.)

@access <word>

Whether the function or variable is public or private. This will be error prone if inferred from the code.

@signature <line>

A signature inferred from a single line of code.

Additional comments

There are available block comments in Lua, and they can also be used in code documented with LuaDoc. The commented blocks will be removed before further processing, making the resulting documentation stripped down to the bare running code.

In Lua a block comment starts like --[[ and run until the corresponding ]]. Actually, if we add an additional leading hyphen then the comment will be turned into a single line comment. That leads to a situation whereby the following code can comment out a piece of code

    --[[
    print(10)         -- no action (comment)
    --]]

Now, if we add a single hyphen to the first line, the code is in again:

    ---[[
    print(10)         --> 10
    --]]

To formalize this a little we will say that LuaDoc only act upon comments that are on a line by themselves. Other block comments are simply left as they are.

Block comments can be specified a bit more, leading to nested comments. The regex we are using for block comments is like \n%s*\-\-%b[](=*)&[].*\]\1\]

External links

• LuaDoc
• @use JSDoc
• Javadoc tool web site
• Javadoc tags and how to write comments

The above documentation is transcluded from Module:Sandbox/Jeblad/LuaDoc/doc. (edit | history)
Editors can experiment in this module's sandbox (create | mirror) and testcases (create) pages.
Subpages of this module.

--- Format documentation of a module and make it linkable
-- The module makes some assumptions about the layout, basically the same as
-- JavaDoc and LuaDoc, but does not follow those examples strictly. Especaially,
-- it makes no attempt to do a deeper analysis of the provided code.
local luadoc = {}

-- don't pollute with globals
require('Module:No globals')

local Frag= {}
Frag.__index = Frag

setmetatable(Frag, {
  __call = function (cls, ...)
    local self = setmetatable({}, cls)
    self:_init(...)
    return self
  end,
})

function Frag:_init( t )
  self['_class'] = t['class']
  self['_summary'] = t['summary']
  self['_desc'] = t['desc']
end

function Frag:renderClass( t )
	local html = mw.html.create( 'div' )
	:addClass( 'tagline' )
	:wikitext( self['_summary'] )
	return html
end

function Frag:renderSummary( t )
	local html = mw.html.create( 'div' )
	:addClass( 'summary' )
	:wikitext( self['_summary'] )
	return html
end

function Frag:renderDesc( t )
	local html = mw.html.create( 'div' )
	:addClass( 'desc' )
	:wikitext( self['_desc'] )
	return html
end

function Frag:render( parent, t )
	parent
		:append(self:renderClass(t))
		:append(self:renderSummary(t))
		:append(self:renderDesc(t))
	return parent
end

local Mod = {}
Mod.__index = Mod

setmetatable(Mod, {
  __index = Frag,
  __call = function (cls, ...)
    local self = setmetatable({}, cls)
    self:_init(...)
    return self
  end,
})

function Mod:_init( t )
  Frag._init(self, t)
end

function Frag:render( parent, t )
	return parent
end

local Var = {}
Var.__index = Var

setmetatable(Var, {
  __index = Frag,
  __call = function (cls, ...)
    local self = setmetatable({}, cls)
    self:_init(...)
    return self
  end,
})

function Var:_init( t )
  Frag._init(self, t)
  self['_var'] = t['var']
end

function Var:renderVar( t )
	local html = mw.html.create( 'div' )
	:addClass( 'var' )
	:wikitext( self['_var'] )
	return html
end

local Func = {}
Func.__index = Func

setmetatable(Func, {
  __index = Frag,
  __call = function (cls, ...)
    local self = setmetatable({}, cls)
    self:_init(...)
    return self
  end,
})

function Func:_init( t )
  Frag._init(self, t)
  self['_param'] = t['param']
  self['_return'] = t['return']
end

function Func:renderParam( t )
	local html = mw.html.create( 'div' )
	:addClass( 'param' )
	:wikitext( self['_param'] )
	return html
end

function Func:renderReturn( t )
	local html = mw.html.create( 'div' )
	:addClass( 'return' )
	:wikitext( self['_return'] )
	return html
end

local parse = {
	['module'] = Mod,
	['function'] = Func,
	['variable'] = Var,
}

local function loadDoc( namespace, text )
	local title = mw.title.new( text, namespace )
	assert( title, 'Unknown title')
	local content = title:getContent()
	assert( content, 'Got no content' )
	return content
end

local function parseFragment( frag )
	if frag._class and frag['var'] then
		for i,v in ipairs(frag['var']) do
			frag._class = 'variable'
			break
		end
	end

	if frag._class and frag['param'] then
		for i,v in ipairs(frag['param']) do
			frag._class = 'function'
			break
		end
	end

	if frag._class and frag['return'] then
		for i,v in ipairs(frag['return']) do
			frag._class = 'function'
			break
		end
	end

	if frag._class and frag['code'] then
		for i,v in ipairs(frag['code']) do
			if line:match( 'function' ) then
				frag._class = 'function'
				break
			end
		end
	end

	local constructor = parse[frag._class]
	assert( constructor, 'Unknown class' )
	
	return constructor( frag )
end

local function parseDoc( code )
	local fragments = {}
	local fragment = { ["_class"] = 'module', ["lines"] = 0 }
	local last = nil
	for line in code:gmatch( '([^\n]+)' ) do
		local desc = line:match( '^\s*---\s*(.+)' )
		if desc then
			if fragment.lines > 0 then
				fragments[1+#fragments] = parseFragment( fragment )
				fragment = { ["_class"] = nil, ["lines"] = 0 }
			end
			fragment ={}
			last = '_desc'
			fragment[last] = desc
		else
			if line:match( '^\s*--' ) then
				local attr, text = line:match( '^\s*--\s*@(\w+)\s+(.*)' )
				if attr then
					last = '_'..attr
					if not fragment[last] then
						fragment[last] = {}
					end
					fragment[last][1+#fragment[last]] = text
				else
					local text = line:match( '^\s*--\s*(.*)' )
					fragment[last][#fragment[last]] = text
				end
			else
				last = '_code'
				fragment[last] = line
			end
		end
	end

	return fragments
end

if 1 or _G['_BDD'] then
	luadoc.Mod = Mod
	luadoc.Var = Var
	luadoc.Func = Func
	luadoc.loadDoc = loadDoc
end

function luadoc.build( frame )
	local docs = {}
	for _,v in ipairs( frame.args ) do
		local str = mw.text.trim( v )
		if str == '' then
			-- do nothing
		else
			-- local name or canonical name, at english only canonical name
			if str:match( '^[mM]module:' ) then
				local namespace = str:match( '^(%S-)%s*:' )
				local text = str:match( ':%s*(.-)%s*$' )
				local code = loadDoc( text, namespace )
				docs[1+#docs] = parseDoc( code )
			end
		end
	end
	local parent = mw.html.create( 'div' )
	for _,v in ipairs( docs ) do
		parent:append(v:render())
	end
	return parent
end

return luadoc