How to Write API Documentation

From WowAce Wiki
Jump to: navigation, search

Please name your documentation page the same as your library's major version. For example, if your library is "Monkey-1.0" then the page is Monkey-1.0

Template for methods

What it looks like What you type

 :<MethodName>(<arg1>, <arg2>, "<arg3>" [, <arg4>])

<Briefing>

Args

<arg1> 
<type> - <description>
<arg2> 
<type> - <description>
<otherType> - <description>
"<arg3>" 
string - <description>
[<arg4>] 
<type> - <description> (defaults: 1)

Returns

<type> - <Description>

Remarks

<Remarks>

Example

self:<MethodName>(<arg1>, <arg2>, "<arg3>" [, <arg4>])
== :<MethodName>(<arg1>, <arg2>, "<arg3>" [, <arg4>]) ==
<Briefing>
=== Args ===
; <arg1> : <type> - <description>
; <arg2> : <type> - <description>
: <otherType> - <description>
; "<arg3>" : string - <description>
; [<arg4>] : <type> - <description> (default: 1)
=== Returns ===
<type> - <Description>
=== Remarks ===
<Remarks>
=== Example ===
 self:<MethodName>(<arg1>, <arg2>, "<arg3>" [, <arg4>])

Where you replace all the words inside <> with what should be appropriate.

Note: if you do not use a section, like Args, Returns, or Remarks, just leave it out. You should always have an example.

Method Examples

What it looks like What you type

 :EatBanana([num])

Make the monkey eat a given amount of bananas

Args

[num] 
number - number of bananas (default: 1)

Example

self:EatBanana(1)
== :EatBanana([num]) ==
Make the monkey eat a given amount of bananas
=== Args ===
; [num] : number - number of bananas (default: 1)
=== Example ===
 self:EatBanana(1)

 :GetNumBananas()

Return the current amount of bananas

Returns

number - The current amount of bananas

Remarks

You start with 0 bananas and gain 1 every 5 minutes.

Example

local num = self:GetNumBananas()
== :GetNumBananas() ==
Return the current amount of bananas
=== Returns ===
The current amount of bananas
=== Remarks ===
You start with 0 bananas and gain 1 every 5 minutes
=== Example ===
 local num = self:GetNumBananas()

 :Talk("phrase")

Make the monkey try to talk.

Args

"phrase" 
string - the phrase you want to make the monkey talk.

Remarks

It'll just end up screaming and flinging poop at you.

Example

self:Talk("Coconut")
== :Talk("phrase") ==
Make the monkey try to talk.
=== Args ===
; "phrase" : string - the phrase you want to make the monkey talk.
=== Remarks ===
It'll just end up screaming and flinging poop at you.
=== Example ===
 self:Talk("Coconut")

Template for fields

What it looks like What you type

.<fieldName>

<type> - <Description>

Example

self.<fieldName> = something
== .<fieldName> ==
<type> - <Description>
=== Example ===
 self.<fieldName> = something

Where you replace all the words inside <> with what should be appropriate.

The same form should be used for fields that are expected to be set and fields that are just meant to be used.