For your repositories, you can put a '.docmeta' file in to provide extra information. Yes, that is a dot followed by 'docmeta'.

.docmeta is a YAML file that goes in the root of your repository project folder. This means /trunk/.docmeta for SVN users and /.docmeta for Git and Hg users.

Remember to use spaces instead of tabs for indentation

Your .docmeta file, if it exists, will be validated when you commit.

Documentor status

The status of the documentor may be viewed at http://www.wowace.com/documenter/. Moderators are able to add packages to the queue.

Specifying a documenter

To add a documenter, you must specify a dictionary or a list of dictionaries in the following form:

type: luadoc
input-files: "**/*.lua"
output-directory: API

which would run luadoc on all lua files in your repository. This would create one page for each lua file under the API page directory on your project.

another example:

-
    type: luadoc
    input-files: "Alpha/**/*.lua"
    output-directory: Alpha
-
    type: luadoc
    input-files: "Bravo/**/*.lua"
    output-directory: Bravo

which would run luadoc on all lua files under the Alpha directory in your repository, then on all lua files under the Bravo directory.

You can also specify individual files to upload to a specific place:

type: luadoc
input-file: Alpha.lua
output-page: "Alpha API"

File Globs

*

Matches any file. Can be restricted by other values in the glob. * will match all files; c* will match all files beginning with c; *c will match all files ending with c; and c will match all files that have c in them (including at the beginning or end). Equivalent to /[^\/]*/ in regexp.

**

Matches directories recursively. Equivalent to /([^\/]+\/)*/ in regexp.

?

Matches any one character. Equivalent to /[^\/]/ in regexp.

[set]

Matches any one character in set. Behaves exactly like character sets in Regexp, including set negation ([^a-z]).

{p,q}

Matches either literal p or literal q. Matching literals may be more than one character in length. More than two literals may be specified. Equivalent to pattern alternation in regexp.

Document types

luadoc

LuaDoc is a reasonably standard documentation generator. It is used outside of games such as WoW. It is highly useful for documenting library or framework APIs.

autodoc

AutoDoc was created for wowace to document library/framework APIs. It is recommended to use LuaDoc instead, but you can still use AutoDoc.

creole

WikiCreole

plain

Plain text

bbcode

|BBCode

html

Safe Html. This is a subset of the html language and is not used to create full HTML pages.

markdown

Markdown is a lightweight markup language.

LuaDoc Documentation Examples

These examples, taken from different code on WowAce will provide you with practical ways to use LuaDoc within your code.

Functions

Example 1

--- API for external addons to initialize the recipe database with a specific profession
-- @name AckisRecipeList:AddRecipeData
-- @usage Used for an external program to load up data regarding a specific profession into the ARL database.
-- @param profession Name of the profession you wish to load data for
-- @return Boolean indicating if the operation was successful.  The recipe database will be populated with appropriate data.

Example 2

--- Iterate over all frames with the given classification.
-- This iterates over only shown frames unless also_hidden is passed in.
-- @param classification the classification to check
-- @param also_hidden also return frames that are hidden
-- @usage for frame in PitBull4:IterateFramesForClassification("player") do
--     doSomethingWith(frame)
-- end
-- @usage for frame in PitBull4:IterateFramesForClassification("party", true) do
--     doSomethingWith(frame)
-- end
-- @return iterator which returns frames

Tables

--- Default options
-- @class table
-- @name default_options
-- @field profile defaults for the profile

Tags

Taken from the LuaDoc manual.

LuaDoc can parse some tags at each function or table documentation. Tags are indicated in the source code with a `@' character followed by the name of the tag:

@param

Describe function parameters. It also requires the name of the parameter.

@see

Refers to other functions or tables.

@return

Describe the returning value or values of the function.

@usage

Describe the usage of the function or variable.

@description

The description of the function or table. This is usually infered automatically.

@name

The name of the function or table definition. This is usually infered from the code analysis, and the programmer does not need to define it. If LuaDoc can infer the name of the function automatically it's even not recomended to define the name explicitally, to avoid redundancy.

@class

If LuaDoc cannot infer the type of documentation (function, table or module definition), the programmer can specify it explicitally.

@field

Describe a table field definition.

@release

Free format string to describe the module or file release.