From 97e4d313ffc563dce216677719bd85f967a18fe6 Mon Sep 17 00:00:00 2001
From: James Whitehead II <jnwhiteh@gmail.com>
Date: Sun, 9 Jan 2011 16:35:09 +0000
Subject: [PATCH] Added comments to API, added source registration

---
 TomTomLite.lua              |   66 +++++++++++++++++++++++++++++++++++++++++++
 sources/Corpse.lua          |    5 ++++
 sources/QuestObjectives.lua |    5 ++++
 3 files changed, 76 insertions(+)

diff --git a/TomTomLite.lua b/TomTomLite.lua
index 1939222..ca2a832 100644
--- a/TomTomLite.lua
+++ b/TomTomLite.lua
@@ -48,6 +48,7 @@ do
             return set
         end
     })
+    addon.sources = {}
 end
 
 function addon:Initialize()
@@ -148,6 +149,66 @@ end
 --  External API
 -------------------------------------------------------------------------]]--
 
+-- Register a new waypoint source for use with TomTomLite. The build-in sources
+-- are 'objective' and 'corpse'. These can just be used in the user interface
+-- to allow the user to filter/mask different sources and to set priority
+-- modifiers.
+--
+-- Arguments:
+--   stype  - A short 'type' string used to identify the source of a waypoint
+--   name   - The localized name of the source, for use in the user interface
+--   desc   - Localized long description of the source type
+--   opt    - A table containing any other options, for future-use
+
+function addon:RegisterSource(stype, name, desc, opt)
+    local sources = {
+        type = stype,
+        name = name,
+        desc = desc,
+    }
+
+    if opt then
+        for k,v in pairs(opt) do
+            if sources[k] then
+                local err = string.format(L["Source '%s' registered with invalid option '%s'"], name, k)
+                error(err)
+            else
+                sources[k] = v
+            end
+        end
+    end
+
+    table.insert(self.sources, source)
+end
+
+-- Add a new waypoint to TomTomLite. This may not cause the waypoint to be
+-- immediately displayed, just simply adds it to the collection of waypoints
+-- that TomTomLite knows about. In general, a waypoint will be added and then
+-- between user options and waypoint priorities one or more may be chosen
+-- to be displayed.
+--
+-- Arguments:
+--   map    - The numeric map ID for the given waypoint. These map ids are
+--            unique for a given map.
+--   floor  - The floor for the given waypoint on the specified map. This
+--            argument may be nil, indicating that the 'default' floor should
+--            be used, and TomTomLite will attempt to choose a sane default.
+--   x      - The x coordinate of the waypoint, specified as a number between 0
+--            and 1. If the number specified is greater than 1, it will be
+--            divided by 100 before being used by TomTomLite.
+--   y      - The y coordinate of the waypoint, following the same format as 'x'
+--   opt    - A table containing other options for the specified waypoint.
+--            Currently the following options are supported:
+--
+--      priority - A number indicating the priority of the waypoint.
+--                 The default priority is 0 and the greatest should be
+--                 100, indicating something that should always be
+--                 displayed, for example the Corpse arrow.
+--
+-- Returns:
+--   waypoint   - A table containing the information about the given waypoint and
+--                serving as a unique identifier for the waypoint within TomTomLite.
+
 function addon:AddWaypoint(map, floor, x, y, opt)
     assert(type(map) == "number")
     assert(type(floor) == "number" or floor == nil)
@@ -173,6 +234,11 @@ function addon:AddWaypoint(map, floor, x, y, opt)
     return waypoint
 end
 
+-- Removes a waypoint entirely from TomTomLite.
+--
+-- Arguments:
+--   waypoint   - The unique waypoint table that was returned by 'AddWaypoint'
+
 function addon:RemoveWaypoint(waypoint)
     for idx, entry in ipairs(self.waypoints) do
         if entry == waypoint then
diff --git a/sources/Corpse.lua b/sources/Corpse.lua
index 3d28b02..f079492 100644
--- a/sources/Corpse.lua
+++ b/sources/Corpse.lua
@@ -5,6 +5,11 @@ local L = addon.L
 --  Corpse arrow module for TomTomLite, example reference module
 -------------------------------------------------------------------]]--
 
+do
+    local desc = L["This source provides a waypoint for your corpse, when you happen to die."]
+    addon:RegisterSource("corpse", L["Corpse"], desc)
+end
+
 local eventFrame = CreateFrame("Frame")
 eventFrame:RegisterEvent("ADDON_LOADED")
 eventFrame:RegisterEvent("PLAYER_ALIVE")
diff --git a/sources/QuestObjectives.lua b/sources/QuestObjectives.lua
index f670c71..4309f9c 100644
--- a/sources/QuestObjectives.lua
+++ b/sources/QuestObjectives.lua
@@ -11,6 +11,11 @@ local L = addon.L
 --  rest. This of course can be overridden by the user
 -------------------------------------------------------------------]]--
 
+do
+    local desc = L["This source provides waypoints for each of the objectives listed in the Blizzard objectives tracker. To add a quest to the tracking list, just shift-click it in your quest log."],
+    addon:RegisterSource("questobj", L["Quest Objectives (tracked)"], desc)
+end
+
 local PRI_FIRST = 15
 local PRI_OTHER = 0
 
-- 
1.7.9.5