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:

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

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