Wowpedia:How to edit API pages

From Wowpedia
Jump to: navigation, search

Icon-policy.svg Wowpedia:Guidelines

AddOn pages
API pages
Assume good faith
Archival
Be bold!
Citation
Disambiguation
Fan fiction
Images

Manual of Style
Signatures
Subpages
Talk pages
Templates
Text removal
Wikiquette
Welcoming

See also: policies, administrators
policy sign

This page is considered a guideline on Wowpedia.

It illustrates standards of conduct, which many editors agree with in principle. However, it is not policy.

Icon-shortcut.pngShortcut: WP:API

The current policy is to separate different kinds of page categories somewhat, and add breadcrumbs to the top of the page to make navigation easier.

  • Don't let these guidelines stop you from creating a page just to add a quick comment about something useful or important that you've learned and want to share! If you just want to write a one-liner, by all means: do so. Just add {{Stub/API}} somewhere in the page so it's easier to find and fix later!
  • Please do not create blank stubs just to get rid of red links. We want the red links there to know that there's no point in clicking it!

Different types of pages

Below is a list of different types of pages, what boilerplates to use, and what page tags to use.

World of Warcraft API page

This page is a user-maintained list of Blizzard-provided functions. When adding and editing function links:

  • There are over one hundred duplicate listings of functions under more than one heading. Look out for unnecessary duplication.
    • Do not place a function under several headings unless you really feel it belongs there.
    • Mikk's API page management scripts can detect duplicates that have gone out of sync.
  • Basic link syntax: [[API DisableAddOn|DisableAddOn]](index or "addonname")   →   DisableAddOn(index or "addonname")
    • The {{api}} template may be used: {{api|DisableAddOn}}(index or "addonname")   →   DisableAddOn{index or "addonname")
  • If a brief description is feasible and not redundant, include it after a hyphen and end with a period:
DisableAddOn(index or "addonname") - Disable the specified AddOn for subsequent sessions.
  • Version or patch numbers should be used rather than simply "NEW!" (and preferably, "removed"). Remember, the page has to make sense a year from now, and beyond. The phrase "added in x.y[.z]" (where x.y.z or x.y is a patch number) is preferred. Use of lowercase keeps the emphasis on the separate description. Recommended formats:
    • Parenthetically after description: SummonRandomCritter() - Summons a random critter companion. (added in 3.3.3)
    • Italicized and separated from description by a double hyphen: SummonRandomCritter() - Summons a random critter companion. -- added in 3.3.3
    • For undocumented functions, simply in place of description: TargetTotem() - added in 3.0.8
    • When an entire section was added in a certain patch, individual notes may be omitted in favor of a brief sentence to cover them all, for example the archaeology functions added in version 4.0.
    • Linking to the patch's WoWpedia page is optional here. Offsite links are unnecessary.
  • Use the proper prefix before a function when applicable. These are explained at the top of the page, and are simply all-caps words or abbreviations with a space before the function listing. Multiple prefixes are allowed, but some prefixes are mutually exclusive and only PROTECTED UI has been observed:
PROTECTED UI ToggleGameMenu - Opens/closes the game menu. Triggers protected functions.

Regular API function pages

Global, honest-to-god APIs, e.g. [UnitName], [AcceptDuel], [GetAddOnDependencies]

Event pages

Events dispatched through the OnEvent script handler, e.g. QUEST_AUTOCOMPLETE

  • Name the page EVENT_NAME.
  • Use e.g. {{wowapievent|Battle.net|Combat}} at the top of the page, which places the page in subcategories of Category:API events
  • Include a one-sentence description of the event, followed by its signature, using appropriate names for its arguments, e.g.
"QUEST_AUTOCOMPLETE", questId
  • Then follow the format of #Regular API function pages format for the arguments, details, examples, patch changes and see also sections.

FrameXML function pages

These are the "UI" tagged functions, e.g. [ChatFrame_AddChannel], [ToggleBackpack]

Other FrameXML pages

For instance [API AuctionFrameAuctions.duration] et al.

Widget method pages

  • Name the page API WidgetName FunctionName.
  • Do not document the same method in all inherited widgets. Only in the base class. (Actually, don't invent new links at all. Just trust what's already in the Widget API page. Flickering's tools get it right.)
  • Use Help:Widget method articles as a basis for the page.
  • Place {{widgetmethod}} at the top of the page (the boilerplate already has it). Places the page in Category:Widget methods.
  • Remember that you can place generic information in and refer to UISUMMARY WidgetName, e.g. UISUMMARY EditBox.

Data type pages

  • Name the page typeName (no prefix to make it easier to link)
  • Place {{wowapitype}} at the top of the page.
  • Not every argument deserves to be described as a stand-alone data type. E.g. if it's just a 1--n index that every novice hacker can grasp, chances are, it doesn't.

User-defined function pages

UI Technical Details pages

Notation and Conventions

Links from World of Warcraft API et al

Example API listing

  • SetMapZoom(continentIndex[, zoneIndex]) - Sets the current world map to a specific continent and optionally zone.
This function takes one or two arguments. The square brackets indicate that the second argument is optional.

Example API with string argument

The quotes around the arguments in this function means that the parameter is a string. It does not mean that the argument is literally "channel" or "name".

Example of an UI Object (widget) method

This example shows that the SetAllPoints() function is called as a method function on a LayoutFrame object. The arguemnt is either a frame, or a frame name (string).

Link Code Examples

: [[API SetMapZoom|SetMapZoom]](continentIndex[,zoneIndex]) - Description
Pages describing individual API functions are named on the form "API FunctionName" (with no argument information).
: [[API LayoutFrame GetHeight|LayoutFrame:GetHeight]]() - Description
Pages describing individual widget methods are named on the form "API ObjectType FunctionName" (with no argument information).

Link Prefixes

  • PROTECTED - function exists, but is protected for Blizzard only code.
If the page exists, put {{protectedapi|<version when it was protected>|<extra info, if appropriate>}} at the top
  • REMOVED - indicates that the function has been removed from the API.
Removed functions should only be listed in Category:World of Warcraft API/Removed Functions
If the page exists, put {{removedapi|<version when it was removed>|<what to use instead, if appropriate>}} at the top
  • UI - indicates that the function is provided by the FrameXML UI code, rather than the core API.
If the page exists, put {{framexmlfunc|<FrameXML/FileNameWhereFunctionIs.lua>}} at the top

Data and Argument Types

The API uses special values for some function arguments, the commonly used types are:

actionSlot - Action button slot numbers (120 in total)
auctionSortId - An identifier for sorting columns in the auction house.
auctionTypeId - An identifier specifying which type of auction to operate on.
bagId - Numbers representing bags you carry, bank bags, bank window, etc
bagType - A bittype identifier representing the type of bags an item can go into or the type of items a bag can carry (New in 2.4.0)
chatTypeId - An identifier for the different chat destination types.
classId - An identifier for character classes.
emoteToken - System names of voice/action emotes
enchantString - An enchant id.
enchantLink - A string that will be clickable, if shown in-game, contains an enchantString.
GUID - A unique identifier for everything that can be interacted with.
inventorySlotName - Names of inventory slots.
inventorySlotId - Current mappings of slot names to numbers. May change.
itemEquipLoc - String representation of where an item may be equipped ("INVTYPE_HEAD", etc)
itemString - An item id with data about enchants, "of" type bonuses, and the item's creator.
itemLink - A string that will be clickable if shown in-game, contains an itemString.
itemType - String classification of an item, ("Armor", "Consumable", etc)
lootMethod - An identifier for the different looting methods (group loot, need before greed, etc)
mapID - A numeric identifier for a world/zone map.
playerName - The name of a player.
questID - A unique numeric identifier for quests.
questLink - A string that will be clickable, if shown in-game, contains a questString.
questString - A quest id with data about the quest, including the level and quest title.
raidIndex - A number between 1 and 40
standingId - Numeric encoding of faction standing.
unitId - An identifier which specifies one of the units the API may reference ("target", "party1", etc)
unitFlag - A bittype indentifier for the relationship between the player and a unit in the combat log (New in 2.4.0)
difficultyIndex - A numeric identifier for dungeon and raid difficulty.


Category:API types has the full list. (Though if something there is not available here: please list it!)


Learning about undocumented functions

So, when you can't go to Wowpedia to learn how a WoW API works, what to do?

  • Ask yourself if the examples really cover everything you need to know:
    • What happens on failure? Does the function return nil or false?
    • That logical test you see, is the function returning 1 or true? It might make a difference to others.
    • Which parameters can be left as nil?
  • TEST your questions. Either by experimenting with the API in an AddOn of yours, or, perhaps easier, use an in-game Lua editor like myDebug!
  • Please help the rest of us and type your findings into Wowpedia :-)

Someone else might have done the hard work without sharing already; if you have a bunch of AddOns installed, try searching in them to see if they use the API. It might tell you more.

See also