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.
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.
- 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"
- Matches any file. Can be restricted by other values in the glob.
*will match all files;
c*will match all files beginning with
*cwill match all files ending with
cwill match all files that have
cin them (including at the beginning or end). Equivalent to
- Matches directories recursively. Equivalent to
- Matches any one character. Equivalent to
- Matches any one character in set. Behaves exactly like character sets in Regexp, including set negation
- Matches either 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.
- 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 was created for wowace to document library/framework APIs. It is recommended to use LuaDoc instead, but you can still use AutoDoc.
- Plain text
- Safe Html. This is a subset of the html language and is not used to create full HTML pages.
- 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.
--- 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.
--- 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
--- Default options -- @class table -- @name default_options -- @field profile defaults for the profile
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:
- Describe function parameters. It also requires the name of the parameter.
- Refers to other functions or tables.
- Describe the returning value or values of the function.
- Describe the usage of the function or variable.
- The description of the function or table. This is usually infered automatically.
- 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.
- If LuaDoc cannot infer the type of documentation (function, table or module definition), the programmer can specify it explicitally.
- Describe a table field definition.
- Free format string to describe the module or file release.