Help:How to document the API
From TheWarWiki
In order to provide a consistent reference for the WAR API, the following practices should be followed when documenting elements of the Lua interface for addons.
Contents |
Page names
Any page about a specific Lua object or API call should be in the API: namespace, with a page name identical to how you'd reference that object/function in Lua. Therefore, global functions should simply be API:FunctionName while objects, subobjects, and their methods should look something like API:ObjectName, API:ObjectName.SubObjectName, and API:ObjectName.SubObjectName.MethodName (with as many dot-references as necessary). Functions and methods should not have arguments or parentheses as part of their page name - use API:CancelSpell, not API:CancelSpell().
Examples
Global functions: API:CancelSpell, API:WStringToString
Objects/Subobjects: API:ChatWindow, API:WindowUtils.Cascade
Object methods: API:WindowUtils.Cascade.Resolve, API:UnitFrames.AddFrame
Style guidelines
- When including small bits of code within a paragraph (such as single function calls/names, et cetera), put it in <code></code> tags -
like this. The only exception to this is if all you are doing is linking to another page - such as API:CancelSpell.
- In function usage examples, italicize anything that would be changed by the user to match their needs - function arguments, names of return variables, and flags:
returnVal = SomeFunction(arg1, arg2).
Templates
When creating a page for a function, object, or method, you should use the appropriate template as follows:
Global function
Usage:
{{API Function
| desc = Returns some values when given some arguments.
| usage = return1, return2 = SampleFunction(arg1, arg2[, arg3])
| args =
{{API Param |arg1|arg1type|arg1desc}}
{{API Param |arg2|arg2type|arg2desc}}
| returns =
{{API Param |return1|return1type|return1desc}}
{{API Param |return1|return1type|return1desc}}
}}
Object (or subobject)
Usage:
{{API Object
| desc = Represents the whatchamacallit, with all associated actions.
| parent = SomeObject.OtherObject
| methods =
{{API Property |method1|function|method1 description}}
| properties =
{{API Property |prop1|prop1type|prop1 description}}
{{API Property |prop2|prop2type|prop2 description}}
}}
Method
Usage:
{{API Method
| desc = Returns some values when given some arguments.
| usage = return1, return2 = SampleObject.SampleMethod(arg1, arg2[, arg3])
| parent = SampleObject
| args =
{{API Param |arg1|arg1type|arg1desc}}
{{API Param |arg2|arg2type|arg2desc}}
| returns =
{{API Param |return1|return1type|return1desc}}
{{API Param |return1|return1type|return1desc}}
}}
See the individual template's pages for more info on their individual attributes. The template should be at the top of the page, with any additional information being added after the template. Also note that these templates automatically add pages that contain them to the appropriate Category:API Functions, Category:API Objects, or Category:API Methods - you don't need to add pages to those categories yourself.
