Autodoc Format

From WowAce Wiki
Jump to: navigation, search

The Autodoc format is intended to allow you to automatically generaterate wiki documentation by adding documentation to relevant methods in your source files. It's a handy way to ensure that the source stays readable and keep your wiki documentation up to date and synched with it!

Documentation is generated from the WowAce repository by a cron job running the Autodoc Script every X minutes. Just commit your changes and the documentation will be automatically generated and available to insert into the wiki. To include a file's documentation in your library's wiki page, add this to your addon's library page:


Documented method selection

Not all methods are documented. By default the following rules apply:

  • Only methods that stricly match function namespace:methodName(arguments) are documented. Methods that match function namespace.SomeName() and namespace.SomeName = function() are ignored.
  • Only one namespace is documented. All others are ignored. The default documented namespace is the one with the highest number of entries.
  • The namespace is stripped from the output,
  • An all-uppercase method like :PLAYER_ENTERING_WORLD is ignored,
  • Methods not matching ^[A-Za-z] (such as Do_Something) are ignored,
  • Methods matching On[A-Z] (such as OnEnableModule) are ignored,

Theses rules can be altered by the following directives :


Enforce the documented namespace.

-- #AUTODOC_NAMESPACE someNamespace

function someNamespace:Method() -- documented

function blob:DoSomeFunnyTrick() -- ignored


Ignore the following method.

function namespace:PrivateMethod()


Assume #NODOC for all the following methods. You have to use #EXPLICIT_DOC or #FORCE_DOC to specify which methods should be documented.


function namespace:PrivateMethod1() -- ignored
function namespace:PrivateMethod2() -- ignored

-- Returns: true
function namespace:PublicMethod()
  return true


Enforce documentation of the following method. This takes precedence over #NODOC, #NODOC_DEFAULT and namespace filtering.

function undocumentedNamespace:GetValue() -- otherwise ignored
function namespace:UNIT_HEALTH() -- otherwise ignored
function namespace:OnEnable() -- otherwise ignored

Comment format

  • You may use both line and block comments.
  • The documenting comments must precede the method definition.
  • Any line that does not belong to one of the documenting sections is ignored.
  • Sections are written in the following order : arguments, notes, returns, example.
  • Unless stated otherwise, empty lines are ignored.
  • All sections are optional.


Describe the arguments.

  • The argument list is taken from the function definition.
  • Arguments must be documented in the same order.
  • Argument names are automatically added in the output.
  • Leading whitespaces are trimmed.
  • Arguments are generally expected to be in "type - description" format, one to a line, but this is flexible.
  • Arguments that appear as "string - description" will be quoted in the function header to indicate their stringiness.
  • Arguments beginning by [optional] are marked as such in the functioh header.


Add notes to the method documentation.

  • Only leading empty lines are ignored.
  • Leading whitespaces are trimmed.
  • Lines starting with "#" are indented by one space in the output, creating code sections.


Describe the return values.


Describe an usage example.

  • If every lines of the example starts with a space or a tab, it is stripped.
  • The whole block is indented by one space in the output, creating a code section.


See for a comprehensive example.

-- Arguments:
-- type - description
-- [optional] type - description
-- Notes:
-- Some notes here
-- They can be multi-line
-- Example:
-- DoSomething()
-- DoSomethingElse()
-- Returns:
-- * boolean - something
-- * string - something else

A more relevant example:

 * Sets the default mixins for a given module.
 * This cannot be called after :NewModule() has been called.
 * This should really only be called if you use the mixins in your prototype.
	list of mixins (up to 20)
	core:SetModuleMixins("AceEvent-2.0", "AceHook-2.0")
function AceModuleCore:SetModuleMixins(...)
	if self.moduleMixins then
		AceModuleCore:error('Cannot call "SetModuleMixins" twice')
	elseif not self.modules then
		AceModuleCore:error("Error initializing class.  Please report error.")
	elseif next(self.modules) then
		AceModuleCore:error('Cannot call "SetModuleMixins" after "NewModule" has been called.')

	self.moduleMixins =  { ... }
	for i,v in ipairs(self.moduleMixins) do
		self.moduleMixins[i] = getlibrary(v)