Autodoc Format

From WowAce Wiki

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:

{{:API_Docs/MyAddon/MyAddonFile.lua}}

Contents 1 Documented method selection 1.1 #AUTODOC_NAMESPACE 1.2 #NODOC 1.3 #NODOC_DEFAULT 1.4 #EXPLICIT_DOC and #FORCE_DOC 2 Comment format 2.1 Arguments: 2.2 Notes: 2.3 Returns: 2.4 Example: 3 Example

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 :

#AUTODOC_NAMESPACE

Enforce the documented namespace.

-- #AUTODOC_NAMESPACE someNamespace

function someNamespace:Method() -- documented
end

function blob:DoSomeFunnyTrick() -- ignored
end

#NODOC

Ignore the following method.

-- #NODOC
function namespace:PrivateMethod()
end

#NODOC_DEFAULT

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

-- #NODOC_DEFAULT

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

-- #EXPLICIT_DOC
-- Returns: true
function namespace:PublicMethod()
  return true
end

#EXPLICIT_DOC and #FORCE_DOC

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

-- #FORCE_DOC
function undocumentedNamespace:GetValue() -- otherwise ignored
end

-- #FORCE_DOC
function namespace:UNIT_HEALTH() -- otherwise ignored
end

-- #FORCE_DOC
function namespace:OnEnable() -- otherwise ignored
end

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.

Arguments:

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.

Notes:

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.

Returns:

Describe the return values.

Example:

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.

Example

See http://svn.wowace.com/wowace/trunk/Threat-2.0/Threat-2.0/Threat-2.0.lua 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:

--[[----------------------------------------------------------------------------------
Notes:
 * 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.
Arguments:
	list of mixins (up to 20)
Example:
	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.')
	end

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