Fandom Developers Wiki
Register
Advertisement

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

Creates docs for a module.
Parameters
NameTypepurpose
pagestringA page to read the docs from e.g. Bananas.
Return typeReturn purpose
stringA string containing the documentation of a module.

createFunctionTables

Creates tables contains function parameters and return types.
Parameters
NameTypepurpose
functionTabletableA table containing all functions in the code, related docs.
Return typeReturn purpose
tableA table based on mw.html containing the function docs.

p.main

Entry point for documenting.
Parameters
NameTypepurpose
frametableA frame object containing a module name as first parameter.
Return typeReturn purpose
stringThe documentation of a particular module.

getDefaultPage

Gets a default mpage, generally a subpage(e.g"/links") of "Global lua modules".
Return typeReturn purpose
stringThe default page containing documentation.

References[]

Advertisement