Вовпедия:Как править страницы об API

Вовпедия:Руководства
Архивирование Изображения Локализация Неоднозначность Оформление статей Подписи Подстраницы Правьте смело! Предполагайте добрые намерения	Страницы аддонов Страницы об API Страницы обсуждений Ссылки на источники Удаление текста Фанфик Шаблоны Этикет
См. также: правила, администраторы

Это страница с руководствами Вовпедии. Оно отображает одобренные большинством редакторов стандарты поведения и не является правилом. Не стесняйтесь предлагать любые изменения этой страницы, но, при существенных правках, просим вас воспользоваться процедурой голосования на её странице обсуждения. См. Вовпедия:Руководства для краткого обзора руководств Вовпедии. См. Категория:Правила для списка предложенных и одобренных руководств Вовпедии.

Задачей текущего руководства является создание удобной навигации по данным видам страниц с помощью определения некоторых категорий и добавления навигационной цепочки в верхней части страницы, а также формирование единых принципов оформления статей об API.

• Не допускайте, чтобы данное руководство останавливало вас при создании страницы, в которой вы хотите лишь указать полезную и важную информацию, которую вы узнали и хотите ею поделиться! Даже если вы хотите добавить всего лишь одну строчку, то, смело добавляйте её, во что бы то ни стало. Но не забывайте в этом случае добавлять в верхней части статьи шаблон {{Заготовка/API}}, чтобы её можно было потом легко найти и дополнить требуемой информацией!
• Просим вас не создавать пустые статьи-заглушки только для того, чтобы избавиться от красных ссылок. Нам нужны такие ссылки, чтобы знать, что за ними нет никаких статей и нет смысла на них нажимать!
• При создании статей также старайтесь придерживаться определённого стиля в оформлении данного вида страниц.

Типы страниц

Ниже представлен список различных типов страниц, которые используются в макетах и тегах.

World of Warcraft API page

Adding and editing function links:

• There's over one hundred duplicate listings of functions under more than one heading. Try to look for duplicates when changing documentation.

• Mikk's API page management scripts can detect duplicates that have gone out of sync

• Do not place a function under several headings unless you really feel it belongs there. See previous point.
• Basic link syntax: [[API DisableAddOn|DisableAddOn]](index or "addonname")   →   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. [UnitName], [AcceptDuel], [GetAddOnDependencies]

• Name the page API FunctionName.
• Use Help:API Function articles as a basis for the page.
• Place {{wowapi}} at the top of the page (the boilerplate already has it). Places the page in Category:World of Warcraft API.

FrameXML function pages

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

• Name the page API FunctionName.
• Use Help:API Function articles as a basis for the page.
• Replace {{wowapi}} with {{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 {{framexml}} at the top of the page. Places the page in Category:FrameXML documentation.

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

• Name the page according to the function name without prefix, e.g. strfindt, or the logical function group, e.g. Table Helpers.
• Place {{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 {{uitech}} at the top of the page. Places the page in Category:UI technical details.

Learning about undocumented functions

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

• 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 WoWWiki :-)

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

• Category:Interface customization templates - Contains the above page tags, and some more
• API Notation and Conventions
• Help:Editing - For the Wiki markup syntax
• Вовпедия:How to edit a page - More general guidelines on editing WoWWiki