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 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}}

Rules

• Only methods in the namespace you specify are documented (e.g. specifying namespace "ThreatLib" will only document methods such as ThreatLib:Foo - no namespace-less methods or ThreatLib.OnCommReceive, etc). If you do not specify a namespace, the namespace with the most qualifying methods will be selected for documenting.
• A method preceeded by a #NODOC directive will not be documented
• An all-uppercase method like :PLAYER_ENTERING_WORLD will not be documented by default
• Methods that do not match ^[A-Za-z] will not be documented by default
• Methods matching On[A-Z] (such as OnEnableModule) will not be documented by default
• You can force a method to be documented with "#EXPLICIT_DOC" or "#FORCE_DOC"
• If you want methods to not be documented by default, place #NODOC_DEFAULT at the top of your file. Only #EXPLICIT_DOC/#FORCE_DOC methods will be documented.
• Recognized headers:
  • Arguments:
  • Notes:
  • Example:
  • Returns:
• 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 to indicate their stringiness.
• You may use both line and block comments

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