AddOn Studio Wiki:How to edit API pages - Revision history

Bear: /* Other General Sections */

2023-08-14T23:15:40Z

Other General Sections

← Older revision		Revision as of 23:15, 14 August 2023
Line 19:		Line 19:

	=== Other General Sections ===		=== Other General Sections ===
	* [[wo:~~development~~]]		* [[wo:Development]]
	** [[wo:HOWTOs]] - various articles that could be about anything relating to WoW Development and getting something done		** [[wo:HOWTOs]] - various articles that could be about anything relating to WoW Development and getting something done
	** [[wo:User_defined_functions\|Snippets]] - cut-and-paste functions that you can use in your addons, submitted by wiki contributors		** [[wo:User_defined_functions\|Snippets]] - cut-and-paste functions that you can use in your addons, submitted by wiki contributors

Bear at 23:15, 14 August 2023

2023-08-14T23:15:24Z

← Older revision		Revision as of 23:15, 14 August 2023
Line 2:		Line 2:

	== Documentation Structure ==		== Documentation Structure ==
	The following categories represent the various places documentation and other content should be placed as related to [[wo:~~development~~]]. WoW development covers more than just the '''game client''', and not everything here is user interface customization or macro related.		The following categories represent the various places documentation and other content should be placed as related to [[wo:Development]]. WoW development covers more than just the '''game client''', and not everything here is user interface customization or macro related.

	=== Major Reference Sections ===		=== Major Reference Sections ===

	* [[wo:~~development~~]]		* [[wo:Development]]
	** [[wo:UI Customization]] - major category primarily covering the '''game client''' public APIs and facilites		** [[wo:UI Customization]] - major category primarily covering the '''game client''' public APIs and facilites
	*** [[wo:AddOn]] - this section is a ''reference'' for AddOn development itself, including file formats, rules, and getting started		*** [[wo:AddOn]] - this section is a ''reference'' for AddOn development itself, including file formats, rules, and getting started

Bear at 23:14, 14 August 2023

2023-08-14T23:14:38Z

← Older revision		Revision as of 23:14, 14 August 2023
Line 2:		Line 2:

	== Documentation Structure ==		== Documentation Structure ==
	The following categories represent the various places documentation and other content should be placed as related to [[~~WoW~~ development]]. WoW development covers more than just the '''game client''', and not everything here is user interface customization or macro related.		The following categories represent the various places documentation and other content should be placed as related to [[wo:development]]. WoW development covers more than just the '''game client''', and not everything here is user interface customization or macro related.

	=== Major Reference Sections ===		=== Major Reference Sections ===
Line 29:		Line 29:
	* Please do not create blank stubs just to get rid of red links. We ''want'' the red links there to know that it may need documentation!		* Please do not create blank stubs just to get rid of red links. We ''want'' the red links there to know that it may need documentation!

	* Brushing up on the [[~~AddOn Studio Wiki:~~API notation and conventions]] might be a good idea		* Brushing up on the [[\API notation and conventions]] might be a good idea

	== Different types of pages ==		== Different types of pages ==

Bear at 23:11, 14 August 2023

2023-08-14T23:11:58Z

Bear: Created page with "{{guidelines}} {{guideline|shortcut=WW:API}} {{clrl}} == Documentation Structure == The following categories represent the various places documentation and other content shou..."

2020-05-14T06:19:41Z

Created page with "{{guidelines}} {{guideline|shortcut=WW:API}} {{clrl}} == Documentation Structure == The following categories represent the various places documentation and other content shou..."

New page

{{guideline}}

== Documentation Structure ==
The following categories represent the various places documentation and other content should be placed as related to [[WoW development]]. WoW development covers more than just the '''game client''', and not everything here is user interface customization or macro related.

=== Major Reference Sections ===

* [[WoW development]]
** [[UI Customization]] - major category primarily covering the '''game client''' public APIs and facilites
*** [[WoW AddOn]] - this section is a ''reference'' for AddOn development itself, including file formats, rules, and getting started
*** [[XML UI]] - this section is a ''reference'' and includes all the Ui XML related documenation, including widget docs as related to XML
*** [[Widget API]] - this section is a ''reference'' for all of the Lua interface for the Widgets, only
*** [[WoW API]] - this section is a ''reference'' for all of the Lua interface related free standing WoW API functions and conventions, only
*** [[Lua functions|WoW Lua]] - this section is a ''reference'' for WoW version Lua runtime and any custom functions or conventions
*** [[Event API]] - this section is a ''reference'' for all of the game events
*** [[Macro API]] - this seciton is a ''reference'' for Macro and slash command development
*** [[:Category:Console variables|CVars]] - this section is a ''reference'' for all the game client 'console variables'
** [[Web API]] - major category for the public '''Community Web Platform''' and any other web related factilites

=== Other General Sections ===
* [[WoW development]]
** [[WoW HOWTOs]] - various articles that could be about anything relating to WoW Development and getting something done
** [[User_defined_functions|Snippets]] - cut-and-paste functions that you can use in your addons, submitted by wiki contributors
** [[:Category:UI technical details|UI Tech]] - contains various documents that describe the UI technical details for the WoW UI system

== Policies ==
In most cases this has been taken care of for you, by using the <nowiki>{{templates}}</nowiki> already created for each major category.

* Please do not create blank stubs just to get rid of red links. We ''want'' the red links there to know that it may need documentation!

* Brushing up on the [[AddOn Studio Wiki:API notation and conventions]] might be a good idea

== Different types of pages ==
Please reference the major and general doumentation categories in [[#API Documentation Structure|API Documentation Structure]] above. Just following exising conventions for these and other categories, and noticing how these pages were done is usually the best way, and should be your primary self-documented guide for adding and editing wow wiki development content.

Below is a list of some of the different types of pages, with a few additional guidelines.

== Widget reference ==
Guidelines for editing the [[UI Customization]] [[Widget API]] reference pages.

* Only document the a widget method in its own base class. Do not document the same method in all inherited widgets.
* Document new methods or other changes in the [[Widget API]] page first, even if that's the only place.
* Use [[Help:Widget method articles]] as a basis for the page.
* The 'UISUMMARY WidgetName', e.g. <nowiki>[[UISUMMARY EditBox]]</nowiki> is obsolete, use a 'UIOBJECT WidgetName' page instead.
* Use the {{t|apiwidget}} template for referencing links. Prefer method links to the [[Widget API]] page from outside the widget pages.

=== A Widget page ===
* Name the page 'UIOBJECT WidgetName', like 'UIOBJECT Slider'.
* Place <nowiki>{{widget|WidgetName}}</nowiki> at the top of the page (the boilerplate already has it).

=== A Widget Method page ===
* Name the page 'API WidgetName FunctionName', like 'API Slider SetValueStep'.
* Place <nowiki>{{widgetmethod|WidgetName}}</nowiki> at the top of the page (the boilerplate already has it).

== WoW API page ==
Adding and editing function links:

* Do not place a function under several headings unless you ''really'' feel it belongs there. See previous point.
* Basic link syntax: <code><nowiki>[[API DisableAddOn|DisableAddOn]](index or "addonname")</nowiki></code>   →   [[API DisableAddOn|DisableAddOn]](index or "addonname")
** See [[API Notation and Conventions]] for a more thorough explanation
* Don't just say "NEW!" or "REMOVED!". ''Say in which version!'' It may be obvious to you when you write it, since it's the current one, but the page has to make sense three months from now, too. And more.

=== Regular API function pages ===
Global, honest-to-god APIs, e.g. [[[API UnitName|UnitName]]], [[[API AcceptDuel|AcceptDuel]]], [[[API GetAddOnDependencies|GetAddOnDependencies]]]

* Name the page <tt style="border-bottom: 1px dotted;">API ''FunctionName''</tt>.
* Use [[Help:API Function articles]] as a basis for the page.
* Place {{t|wowapi}} at the top of the page (the boilerplate already has it). Places the page in [[:Category:World of Warcraft API]].

=== Learning about undocumented functions ===
So when you can't find a reference to learn how a WoW API works, what to do?

* [[Viewing Blizzard's WoW user interface code|Look in FrameXML]] to learn how Blizzard themselves uses the API.

* 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 the wiki :-)

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.

== FrameXML function pages ==
These are the "UI" tagged functions, e.g. [[[API ChatFrame AddChannel|ChatFrame_AddChannel]]], [[[API ToggleBackpack|ToggleBackpack]]]

* Name the page <tt style="border-bottom: 1px dotted;">API ''FunctionName''</tt>.
* Use [[Help:API Function articles]] as a basis for the page.
* Replace {{t|wowapi}} with {{t|framexmlfunc|FrameXML/FileWhereFunctionIsDefined.lua}} at the top of the page. Places the page in [[:Category:FrameXML documentation]].

=== Other FrameXML pages ===
For instance [[[API AuctionFrameAuctions.duration]]] et al.

* Use {{t|framexml}} at the top of the page. Places the page in [[:Category:FrameXML documentation]].

== Data type pages ==
* Name the page <tt style="border-bottom: 1px dotted;">''typeName''</tt> (no prefix to make it easier to link)
* Place {{t|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 ===
* Name the page according to the function name without prefix, e.g. [[strfindt]], or the logical function group, e.g. [[Table Helpers]].
* Place {{t|userfunc}} at the top of the page (the boilerplate already has it). Places the page in [[:Category:User defined functions]].

== UI Technical Details pages ==
* Place {{t|uitech}} at the top of the page. Places the page in [[:Category:UI technical details]].

== See also ==
* [[:Category:Interface customization templates]] - Contains the above page tags, and some more
* [[API Notation and Conventions]]
* [[Help:Editing]] - For the Wiki markup syntax
[[Category:Interface customization]]
[[Category:Web API]]
[[Category:WoW development]]

← Older revision		Revision as of 23:11, 14 August 2023
Line 6:		Line 6:
	=== Major Reference Sections ===		=== Major Reference Sections ===

	* [[~~WoW~~ development]]		* [[wo:development]]
	** [[UI Customization]] - major category primarily covering the '''game client''' public APIs and facilites		** [[wo:UI Customization]] - major category primarily covering the '''game client''' public APIs and facilites
	*** [[~~WoW~~ AddOn]] - this section is a ''reference'' for AddOn development itself, including file formats, rules, and getting started		*** [[wo:AddOn]] - this section is a ''reference'' for AddOn development itself, including file formats, rules, and getting started
	*** [[XML UI]] - this section is a ''reference'' and includes all the Ui XML related documenation, including widget docs as related to XML		*** [[wo:XML UI]] - this section is a ''reference'' and includes all the Ui XML related documenation, including widget docs as related to XML
	*** [[Widget API]] - this section is a ''reference'' for all of the Lua interface for the Widgets, only		*** [[wo:Widget API]] - this section is a ''reference'' for all of the Lua interface for the Widgets, only
	*** [[WoW API]] - this section is a ''reference'' for all of the Lua interface related free standing WoW API functions and conventions, only		*** [[wo:WoW API]] - this section is a ''reference'' for all of the Lua interface related free standing WoW API functions and conventions, only
	*** [[Lua functions\|WoW Lua]] - this section is a ''reference'' for WoW version Lua runtime and any custom functions or conventions		*** [[wo:Lua functions\|WoW Lua]] - this section is a ''reference'' for WoW version Lua runtime and any custom functions or conventions
	*** [[Event API]] - this section is a ''reference'' for all of the game events		*** [[wo:Event API]] - this section is a ''reference'' for all of the game events
	*** [[Macro API]] - this seciton is a ''reference'' for Macro and slash command development		*** [[wo:Macro API]] - this seciton is a ''reference'' for Macro and slash command development
	*** [[:Category:Console variables\|CVars]] - this section is a ''reference'' for all the game client 'console variables'		*** [[:Category:Console variables\|CVars]] - this section is a ''reference'' for all the game client 'console variables'
	** [[Web API]] - major category for the public '''Community Web Platform''' and any other web related factilites		** [[wo:Web API]] - major category for the public '''Community Web Platform''' and any other web related factilites

	=== Other General Sections ===		=== Other General Sections ===
	* [[~~WoW~~ development]]		* [[wo:development]]
	** [[~~WoW~~ HOWTOs]] - various articles that could be about anything relating to WoW Development and getting something done		** [[wo:HOWTOs]] - various articles that could be about anything relating to WoW Development and getting something done
	** [[User_defined_functions\|Snippets]] - cut-and-paste functions that you can use in your addons, submitted by wiki contributors		** [[wo:User_defined_functions\|Snippets]] - cut-and-paste functions that you can use in your addons, submitted by wiki contributors
	** [[:Category:UI technical details\|UI Tech]] - contains various documents that describe the UI technical details for the WoW UI system		** [[:Category:UI technical details\|UI Tech]] - contains various documents that describe the UI technical details for the WoW UI system

Line 37:		Line 37:

	== Widget reference ==		== Widget reference ==
	Guidelines for editing the [[UI Customization]] [[Widget API]] reference pages.		Guidelines for editing the [[wo:UI Customization]] [[wo:Widget API]] reference pages.

	* Only document the a widget method in its own base class. Do not document the same method in all inherited widgets.		* Only document the a widget method in its own base class. Do not document the same method in all inherited widgets.
	* Document new methods or other changes in the [[Widget API]] page first, even if that's the only place.		* Document new methods or other changes in the [[wo:Widget API]] page first, even if that's the only place.
	* Use [[Help:Widget method articles]] as a basis for the page.		* Use [[Help:Widget method articles]] as a basis for the page.
	* The 'UISUMMARY WidgetName', e.g. <nowiki>[[UISUMMARY EditBox]]</nowiki> is obsolete, use a 'UIOBJECT WidgetName' page instead.		* The 'UISUMMARY WidgetName', e.g. <nowiki>[[UISUMMARY EditBox]]</nowiki> is obsolete, use a 'UIOBJECT WidgetName' page instead.
	* Use the {{t\|apiwidget}} template for referencing links. Prefer method links to the [[Widget API]] page from outside the widget pages.		* Use the {{t\|apiwidget}} template for referencing links. Prefer method links to the [[wo:Widget API]] page from outside the widget pages.

	=== A Widget page ===		=== A Widget page ===
Line 57:		Line 57:

	* Do not place a function under several headings unless you ''really'' feel it belongs there. See previous point.		* Do not place a function under several headings unless you ''really'' feel it belongs there. See previous point.
	* Basic link syntax: <code><nowiki>[[API DisableAddOn\|DisableAddOn]](index or "addonname")</nowiki></code>   →   [[API DisableAddOn\|DisableAddOn]](index or "addonname")		* Basic link syntax: <code><nowiki>[[API DisableAddOn\|DisableAddOn]](index or "addonname")</nowiki></code>   →   [[wo:API DisableAddOn\|DisableAddOn]](index or "addonname")
	** <small>See [[API Notation and Conventions]] for a more thorough explanation</small>		** <small>See [[wo:API Notation and Conventions]] for a more thorough explanation</small>
	* Don't just say "NEW!" or "REMOVED!". ''Say in which version!'' It may be obvious to you when you write it, since it's the current one, but the page has to make sense three months from now, too. And more.		* Don't just say "NEW!" or "REMOVED!". ''Say in which version!'' It may be obvious to you when you write it, since it's the current one, but the page has to make sense three months from now, too. And more.

	=== Regular API function pages ===		=== Regular API function pages ===
	<small>Global, honest-to-god APIs, e.g. [[[API UnitName\|UnitName]]], [[[API AcceptDuel\|AcceptDuel]]], [[[API GetAddOnDependencies\|GetAddOnDependencies]]]</small>		<small>Global, honest-to-god APIs, e.g. [[[wo:API UnitName\|UnitName]]], [[[wo:API AcceptDuel\|AcceptDuel]]], [[[wo:API GetAddOnDependencies\|GetAddOnDependencies]]]</small>

	* Name the page <tt style="border-bottom: 1px dotted;">API ''FunctionName''</tt>.		* Name the page <tt style="border-bottom: 1px dotted;">API ''FunctionName''</tt>.
Line 71:		Line 71:
	So when you can't find a reference to learn how a WoW API works, what to do?		So when you can't find a reference to learn how a WoW API works, what to do?

	* [[Viewing Blizzard's WoW user interface code\|Look in FrameXML]] to learn how Blizzard themselves uses the API.		* [[wo:Viewing Blizzard's WoW user interface code\|Look in FrameXML]] to learn how Blizzard themselves uses the API.

	* Ask yourself if the examples really cover everything you need to know:		* Ask yourself if the examples really cover everything you need to know:
Line 84:		Line 84:

	== FrameXML function pages ==		== FrameXML function pages ==
	<small>These are the "UI" tagged functions, e.g. [[[API ChatFrame AddChannel\|ChatFrame_AddChannel]]], [[[API ToggleBackpack\|ToggleBackpack]]]</small>		<small>These are the "UI" tagged functions, e.g. [[[wo:API ChatFrame AddChannel\|ChatFrame_AddChannel]]], [[[wo:API ToggleBackpack\|ToggleBackpack]]]</small>

	* Name the page <tt style="border-bottom: 1px dotted;">API ''FunctionName''</tt>.		* Name the page <tt style="border-bottom: 1px dotted;">API ''FunctionName''</tt>.
Line 91:		Line 91:

	=== Other FrameXML pages ===		=== Other FrameXML pages ===
	<small>For instance [[[API AuctionFrameAuctions.duration]]] et al.</small>		<small>For instance [[[wo:API AuctionFrameAuctions.duration]]] et al.</small>

	* Use {{t\|framexml}} at the top of the page. Places the page in [[:Category:FrameXML documentation]].		* Use {{t\|framexml}} at the top of the page. Places the page in [[:Category:FrameXML documentation]].
Line 109:		Line 109:
	== See also ==		== See also ==
	* [[:Category:Interface customization templates]] - Contains the above page tags, and some more		* [[:Category:Interface customization templates]] - Contains the above page tags, and some more
	* [[API Notation and Conventions]]		* [[wo:API Notation and Conventions]]
	* [[Help:Editing]] - For the Wiki markup syntax		* [[Help:Editing]] - For the Wiki markup syntax
	[[Category:Interface customization]]		[[Category:Interface customization]]
	[[Category:Web API]]		[[Category:Web API]]
	[[Category:WoW development]]		[[Category:WoW development]]