Wiki

Clone wiki

Lua For IDEA / Setting_Up_Custom_Documentation

Custom documentation can be provided for a custom API.

Custom documentation is provided via a Lua script with the same name and location as the API definition that it documents. The file has the special extension .doclua in order to facilitate this naming.

For example, the World of Warcraft API is named: wow-api.lua, and the documentation is wow-api.doclua.

To support documentation you implement 3 fuctions in the .doclua: getDocumentation, getDocumentationUrl, and getQuickNavigateDocumentation.

In addition 3 functions are provided to help with implementation: log, disableCache, and fetchUrl.

log(string) writes to the idea.log file

disableCache() prevents the Lua script from being cached (useful while developing the script - be sure to remove it)

fetchUrl(string) retrieves a web page as a string.

Below is an example of how to implement a documentation provider.

local BASE_URL = "http://wowprogramming.com"

--- Quickhelp Documentation (ctrl-Q)
-- This is called when the user invokes quick help via ctrl-q, or by
-- having the quickhelp panel open and set to autolookup
-- @param name The name to get documentation for.
-- @return the documentation as an HTML or plain text string
function getDocumentation(name)
    -- Use for development
    -- disableCache()
    -- log(name)
	local data = fetchURL(getDocumentationUrl(name))

    local contentTag = [[<div id='content'>]]
    local footerTag = [[<div id='footer'>]]

    local contentPos = data:find(contentTag);
    local footerPos = data:find(footerTag);

    data = data:sub(contentPos, footerPos)

    data =  data:gsub([[href="]], [[href="]]..BASE_URL)

    data = "<html><h3>" .. name .. "</h3>" .. data .. "<br><br><b>[data provided by wowprogramming.com]</b></html>"

    return data
end

--- External Documentation URL (shift-F1)
-- This is called by shift-F1 on the symbol, or by the
-- external documentation button on the quick help panel
-- @param name The name to get documentation for.
-- @return the URL of the external documentation
function getDocumentationUrl(name) 
	local p1, p2 = string.match(name, "(%a+)\.?(%a*)")
	local url = BASE_URL .. "/docs/api/" .. p1

	if p2 then url = url .. p2 end

	return url
end


--- Quick Navigation Tooltip Text, (ctrl-hover on symbol)
-- This is called when the user ctrl-hovers over a symbol
-- @param name The name to get documentation for.
-- @return the documentation as a plain text string
function getQuickNavigateDocumentation(name)
	local sig = SIGNATURES[name]
	if not sig then return end

	return "[wowprogramming.com]\r\n " .. sig
end


--[[ WOW FUNCTION SIGNATURES ]]

SIGNATURES = {

AbandonQuest = [=[AbandonQuest()]=],
AbandonSkill = [=[AbandonSkill(index)]=],
AcceptAreaSpiritHeal = [=[AcceptAreaSpiritHeal()]=],
AcceptArenaTeam = [=[AcceptArenaTeam()]=],
AcceptBattlefieldPort = [=[AcceptBattlefieldPort(index, accept)]=],
AcceptDuel = [=[AcceptDuel()]=],
AcceptGroup = [=[AcceptGroup()]=],
AcceptGuild = [=[AcceptGuild()]=],
AcceptLevelGrant = [=[AcceptLevelGrant()]=],
AcceptProposal = [=[AcceptProposal()]=],
AcceptQuest = [=[AcceptQuest()]=],
AcceptResurrect = [=[AcceptResurrect()]=],

...

Updated