How to Write API Documentation
From WowAce Wiki
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 |
|---|---|
|
[edit] :<MethodName>(<arg1>, <arg2>, "<arg3>" [, <arg4>])<Briefing> [edit] Args
[edit] Returns<type> - <Description> [edit] Remarks<Remarks> [edit] Exampleself:<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 |
|---|---|
|
[edit] :EatBanana([num])Make the monkey eat a given amount of bananas [edit] Args
[edit] Exampleself: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) |
|
[edit] :GetNumBananas()Return the current amount of bananas [edit] Returnsnumber - The current amount of bananas [edit] RemarksYou start with 0 bananas and gain 1 every 5 minutes. [edit] Examplelocal 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() |
|
[edit] :Talk("phrase")Make the monkey try to talk. [edit] Args
[edit] RemarksIt'll just end up screaming and flinging poop at you. [edit] Exampleself: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 |
|---|---|
|
[edit] .<fieldName><type> - <Description> [edit] Exampleself.<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.
