Codedoc automatically creates documentation of a Lua module by extracting its documentation markup.
- For
@tag
-based documentation, see Docbunto.
Installation[]
Usage[]
This module makes use of the syntax defined in ExpLua to retrieve documentation for a module. For example, with Module:codedoc/sample one could use the following Lua invoke in a talk page to show its code:
{{codedoc|<Module:codedoc/sample>}}
See generated docs in Module talk:Codedoc/sample.
Syntax[]
The syntax is:
{{codedoc|modulename}}
The module name must contain the syntax as described, otherwise it will not retrieve anything.
Documentation syntax[]
As described by the ExpLua author[1]:
For the whole file:
--| Begins a module/file comment, e.g., "this file does *this*". --by Pedro Miller Rabinovitch <miller@inf.puc-rio.br> --$Id: myfile.lua,v 1.12 2003/10/17 00:13:56 miller Exp $ --TODO lots of stuff.(Both --by and --TODO can be abbreviated to --b and --T)
Preceding each function:
--% This is the purpose of the function, i.e., what it *does*. --- And this is the second line, which will concatenated to --- the others. --@ first (string) Text of the first parameter --@ what (table) The second parameter is the table used for an --- example --@ [...] (any) Optional parameters to the called whatever --: (number) Number of whatevers done or nil if an error occured function Module:MyFunction( first, what, ... )
Description[]
The syntax relies on adding comments with special characters that have a specific meaning, as described below:
--|
— is used to describe the module itself--by
— contains author info--TODO
— contains any todo notes--%
— describes the purpose of the function--@
— contains information about the parameters (format: "parameter name (parameter type) description")--:
— contains the description of the values returned by a function (format: "return type and description")
Note that by default the module details (author, etc.) are hidden by a setting in the script, but this can be overwritten.
Module information
Functions
p.createDocs
Name | Type | purpose |
---|---|---|
page | string | A page to read the docs from e.g. Bananas. |
Return type | Return purpose |
---|---|
string | A string containing the documentation of a module. |
createFunctionTables
Name | Type | purpose |
---|---|---|
functionTable | table | A table containing all functions in the code, related docs. |
Return type | Return purpose |
---|---|
table | A table based on mw.html containing the function docs. |
p.main
Name | Type | purpose |
---|---|---|
frame | table | A frame object containing a module name as first parameter. |
Return type | Return purpose |
---|---|
string | The documentation of a particular module. |
getDefaultPage
Return type | Return purpose |
---|---|
string | The default page containing documentation. |