Add LLEventAPI class, formalizing the mechanism by which we wrap a C++ API

with an event API. In addition to the LLEventPump name on which to listen,
LLEventAPI accepts a documentation string for event API introspection.
Give every LLEventDispatcher::add() overload a new documentation string
parameter for event API introspection.
Convert every existing event API to new conventions, introducing suitable
documentation strings for the API and each of its operations.

15 files changed, 86 insertions, 48 deletions

diff --git a/indra/newview/llagentlistener.cpp b/indra/newview/llagentlistener.cpp
index 0f00078b33..3da6a4e3f4 100644
--- a/indra/newview/llagentlistener.cpp
+++ b/indra/newview/llagentlistener.cpp
@@ -22,12 +22,20 @@
 #include "llviewerregion.h"
 
 LLAgentListener::LLAgentListener(LLAgent &agent)
-  : LLDispatchListener("LLAgent", "op"),
+  : LLEventAPI("LLAgent",
+               "LLAgent listener to (e.g.) teleport, sit, stand, etc."),
     mAgent(agent)
 {
-	add("requestTeleport", &LLAgentListener::requestTeleport);
-	add("requestSit", &LLAgentListener::requestSit);
-	add("requestStand", &LLAgentListener::requestStand);
+	add("requestTeleport",
+        "Teleport: [\"regionname\"], [\"x\"], [\"y\"], [\"z\"]\n"
+        "If [\"skip_confirmation\"] is true, use LLURLDispatcher rather than LLCommandDispatcher.",
+        &LLAgentListener::requestTeleport);
+	add("requestSit",
+        "Ask to sit on the object specified in [\"obj_uuid\"]",
+        &LLAgentListener::requestSit);
+	add("requestStand",
+        "Ask to stand up",
+        &LLAgentListener::requestStand);
 }
 
 void LLAgentListener::requestTeleport(LLSD const & event_data) const
diff --git a/indra/newview/llagentlistener.h b/indra/newview/llagentlistener.h
index 6f0b5a54c5..eed6922b3e 100644
--- a/indra/newview/llagentlistener.h
+++ b/indra/newview/llagentlistener.h
@@ -13,12 +13,12 @@
 #ifndef LL_LLAGENTLISTENER_H
 #define LL_LLAGENTLISTENER_H
 
-#include "lleventdispatcher.h"
+#include "lleventapi.h"
 
 class LLAgent;
 class LLSD;
 
-class LLAgentListener : public LLDispatchListener
+class LLAgentListener : public LLEventAPI
 {
 public:
 	LLAgentListener(LLAgent &agent);
diff --git a/indra/newview/llappviewer.cpp b/indra/newview/llappviewer.cpp
index ddb6589b49..845a264327 100644
--- a/indra/newview/llappviewer.cpp
+++ b/indra/newview/llappviewer.cpp
@@ -207,7 +207,7 @@
 #pragma warning (disable:4702)
 #endif
 
-static LLAppViewerListener sAppViewerListener("LLAppViewer", LLAppViewer::instance);
+static LLAppViewerListener sAppViewerListener(LLAppViewer::instance);
 
 ////// Windows-specific includes to the bottom - nasty defines in these pollute the preprocessor
 //
diff --git a/indra/newview/llappviewerlistener.cpp b/indra/newview/llappviewerlistener.cpp
index 3259309eee..adb5f43c1a 100644
--- a/indra/newview/llappviewerlistener.cpp
+++ b/indra/newview/llappviewerlistener.cpp
@@ -19,14 +19,18 @@
 // other Linden headers
 #include "llappviewer.h"
 
-LLAppViewerListener::LLAppViewerListener(const std::string& pumpname,
-                                         const LLAppViewerGetter& getter):
-    LLDispatchListener(pumpname, "op"),
+LLAppViewerListener::LLAppViewerListener(const LLAppViewerGetter& getter):
+    LLEventAPI("LLAppViewer",
+               "LLAppViewer listener to (e.g.) request shutdown"),
     mAppViewerGetter(getter)
 {
     // add() every method we want to be able to invoke via this event API.
-    add("requestQuit", &LLAppViewerListener::requestQuit);
-    add("forceQuit", &LLAppViewerListener::forceQuit);
+    add("requestQuit",
+        "Ask to quit nicely",
+        &LLAppViewerListener::requestQuit);
+    add("forceQuit",
+        "Quit abruptly",
+        &LLAppViewerListener::forceQuit);
 }
 
 void LLAppViewerListener::requestQuit(const LLSD& event)
diff --git a/indra/newview/llappviewerlistener.h b/indra/newview/llappviewerlistener.h
index 73227cb95a..deedcbc179 100644
--- a/indra/newview/llappviewerlistener.h
+++ b/indra/newview/llappviewerlistener.h
@@ -12,20 +12,19 @@
 #if ! defined(LL_LLAPPVIEWERLISTENER_H)
 #define LL_LLAPPVIEWERLISTENER_H
 
-#include "lleventdispatcher.h"
+#include "lleventapi.h"
 #include <boost/function.hpp>
 
 class LLAppViewer;
 class LLSD;
 
 /// Listen on an LLEventPump with specified name for LLAppViewer request events.
-class LLAppViewerListener: public LLDispatchListener
+class LLAppViewerListener: public LLEventAPI
 {
 public:
     typedef boost::function<LLAppViewer*(void)> LLAppViewerGetter;
-    /// Specify the pump name on which to listen, and bind the LLAppViewer
-    /// instance to use (e.g. LLAppViewer::instance()).
-    LLAppViewerListener(const std::string& pumpname, const LLAppViewerGetter& getter);
+    /// Bind the LLAppViewer instance to use (e.g. LLAppViewer::instance()).
+    LLAppViewerListener(const LLAppViewerGetter& getter);
 
 private:
     void requestQuit(const LLSD& event);
diff --git a/indra/newview/llfloaterabout.cpp b/indra/newview/llfloaterabout.cpp
index b01293d17c..80b0a430e0 100644
--- a/indra/newview/llfloaterabout.cpp
+++ b/indra/newview/llfloaterabout.cpp
@@ -64,7 +64,7 @@
 #include "llwindow.h"
 #include "stringize.h"
 #include "llsdutil_math.h"
-#include "lleventdispatcher.h"
+#include "lleventapi.h"
 
 #if LL_WINDOWS
 #include "lldxhardware.h"
@@ -302,13 +302,17 @@ static std::string get_viewer_release_notes_url()
 	return LLWeb::escapeURL(url.str());
 }
 
-class LLFloaterAboutListener: public LLDispatchListener
+class LLFloaterAboutListener: public LLEventAPI
 {
 public:
 	LLFloaterAboutListener():
-		LLDispatchListener("LLFloaterAbout", "op")
+		LLEventAPI("LLFloaterAbout",
+                   "LLFloaterAbout listener to retrieve About box info")
 	{
-		add("getInfo", &LLFloaterAboutListener::getInfo, LLSD().insert("reply", LLSD()));
+		add("getInfo",
+            "Request an LLSD::Map containing information used to populate About box",
+            &LLFloaterAboutListener::getInfo,
+            LLSD().insert("reply", LLSD()));
 	}
 
 private:
diff --git a/indra/newview/lllogininstance.cpp b/indra/newview/lllogininstance.cpp
index e5f347ddc4..945294f3f2 100644
--- a/indra/newview/lllogininstance.cpp
+++ b/indra/newview/lllogininstance.cpp
@@ -73,9 +73,9 @@ LLLoginInstance::LLLoginInstance() :
 {
 	mLoginModule->getEventPump().listen("lllogininstance", 
 		boost::bind(&LLLoginInstance::handleLoginEvent, this, _1));
-	mDispatcher.add("fail.login", boost::bind(&LLLoginInstance::handleLoginFailure, this, _1));
-	mDispatcher.add("connect",    boost::bind(&LLLoginInstance::handleLoginSuccess, this, _1));
-	mDispatcher.add("disconnect", boost::bind(&LLLoginInstance::handleDisconnect, this, _1));
+	mDispatcher.add("fail.login", "", boost::bind(&LLLoginInstance::handleLoginFailure, this, _1));
+	mDispatcher.add("connect",    "", boost::bind(&LLLoginInstance::handleLoginSuccess, this, _1));
+	mDispatcher.add("disconnect", "", boost::bind(&LLLoginInstance::handleDisconnect, this, _1));
 }
 
 LLLoginInstance::~LLLoginInstance()
diff --git a/indra/newview/lluilistener.cpp b/indra/newview/lluilistener.cpp
index 9c643e78de..8b4cfa7248 100644
--- a/indra/newview/lluilistener.cpp
+++ b/indra/newview/lluilistener.cpp
@@ -20,10 +20,16 @@
 #include "lluictrl.h"
 #include "llerror.h"
 
-LLUIListener::LLUIListener(const std::string& name):
-    LLDispatchListener(name, "op")
+LLUIListener::LLUIListener():
+    LLEventAPI("UI",
+               "LLUICtrl::CommitCallbackRegistry listener.\n"
+               "Capable of invoking any function (with parameter) you can specify in XUI.")
 {
-    add("call", &LLUIListener::call, LLSD().insert("function", LLSD()));
+    add("call",
+        "Invoke the operation named by [\"function\"], passing [\"parameter\"],\n"
+        "as if from a user gesture on a menu -- or a button click.",
+        &LLUIListener::call,
+        LLSD().insert("function", LLSD()));
 }
 
 void LLUIListener::call(const LLSD& event) const
diff --git a/indra/newview/lluilistener.h b/indra/newview/lluilistener.h
index ea904a99ff..8605d60bd3 100644
--- a/indra/newview/lluilistener.h
+++ b/indra/newview/lluilistener.h
@@ -12,15 +12,15 @@
 #if ! defined(LL_LLUILISTENER_H)
 #define LL_LLUILISTENER_H
 
-#include "lleventdispatcher.h"
+#include "lleventapi.h"
 #include <string>
 
 class LLSD;
 
-class LLUIListener: public LLDispatchListener
+class LLUIListener: public LLEventAPI
 {
 public:
-    LLUIListener(const std::string& name);
+    LLUIListener();
 
 private:
     void call(const LLSD& event) const;
diff --git a/indra/newview/llviewercontrollistener.cpp b/indra/newview/llviewercontrollistener.cpp
index ecba1b8eb0..0b9db1b906 100644
--- a/indra/newview/llviewercontrollistener.cpp
+++ b/indra/newview/llviewercontrollistener.cpp
@@ -18,12 +18,22 @@
 LLViewerControlListener gSavedSettingsListener;
 
 LLViewerControlListener::LLViewerControlListener()
-	: LLDispatchListener("LLViewerControl",  "group")
+	: LLEventAPI("LLViewerControl",
+                 "LLViewerControl listener: set, toggle or set default for various controls",
+                 "group")
 {
-	add("Global", boost::bind(&LLViewerControlListener::set, &gSavedSettings, _1));
-	add("PerAccount", boost::bind(&LLViewerControlListener::set, &gSavedPerAccountSettings, _1));
-	add("Warning", boost::bind(&LLViewerControlListener::set, &gWarningSettings, _1));
-	add("Crash", boost::bind(&LLViewerControlListener::set, &gCrashSettings, _1));
+	add("Global",
+        "Set gSavedSettings control [\"key\"] to value [\"value\"]",
+        boost::bind(&LLViewerControlListener::set, &gSavedSettings, _1));
+	add("PerAccount",
+        "Set gSavedPerAccountSettings control [\"key\"] to value [\"value\"]",
+        boost::bind(&LLViewerControlListener::set, &gSavedPerAccountSettings, _1));
+	add("Warning",
+        "Set gWarningSettings control [\"key\"] to value [\"value\"]",
+        boost::bind(&LLViewerControlListener::set, &gWarningSettings, _1));
+	add("Crash",
+        "Set gCrashSettings control [\"key\"] to value [\"value\"]",
+        boost::bind(&LLViewerControlListener::set, &gCrashSettings, _1));
 
 #if 0
 	add(/*"toggleControl",*/ "Global", boost::bind(&LLViewerControlListener::toggleControl, &gSavedSettings, _1));
diff --git a/indra/newview/llviewercontrollistener.h b/indra/newview/llviewercontrollistener.h
index cacf97e908..88afbb871d 100644
--- a/indra/newview/llviewercontrollistener.h
+++ b/indra/newview/llviewercontrollistener.h
@@ -12,12 +12,12 @@
 #ifndef LL_LLVIEWERCONTROLLISTENER_H
 #define LL_LLVIEWERCONTROLLISTENER_H
 
-#include "lleventdispatcher.h"
+#include "lleventapi.h"
 
 class LLControlGroup;
 class LLSD;
 
-class  LLViewerControlListener : public LLDispatchListener
+class  LLViewerControlListener : public LLEventAPI
 {
 public:
 	LLViewerControlListener();
diff --git a/indra/newview/llviewermenu.cpp b/indra/newview/llviewermenu.cpp
index 820f709ba5..976d89a5b7 100644
--- a/indra/newview/llviewermenu.cpp
+++ b/indra/newview/llviewermenu.cpp
@@ -415,7 +415,7 @@ public:
 
 static LLMenuParcelObserver* gMenuParcelObserver = NULL;
 
-static LLUIListener sUIListener("UI");
+static LLUIListener sUIListener;
 
 LLMenuParcelObserver::LLMenuParcelObserver()
 {
diff --git a/indra/newview/llviewerwindow.cpp b/indra/newview/llviewerwindow.cpp
index 6b0f8814b9..d69cc5999c 100644
--- a/indra/newview/llviewerwindow.cpp
+++ b/indra/newview/llviewerwindow.cpp
@@ -1212,7 +1212,7 @@ LLViewerWindow::LLViewerWindow(
 	mStatesDirty(false),
 	mIsFullscreenChecked(false),
 	mCurrResolutionIndex(0),
-    mViewerWindowListener(new LLViewerWindowListener("LLViewerWindow", this))
+    mViewerWindowListener(new LLViewerWindowListener(this))
 {
 	LLNotificationChannel::buildChannel("VW_alerts", "Visible", LLNotificationFilters::filterBy<std::string>(&LLNotification::getType, "alert"));
 	LLNotificationChannel::buildChannel("VW_alertmodal", "Visible", LLNotificationFilters::filterBy<std::string>(&LLNotification::getType, "alertmodal"));
diff --git a/indra/newview/llviewerwindowlistener.cpp b/indra/newview/llviewerwindowlistener.cpp
index a890b042ae..de57788271 100644
--- a/indra/newview/llviewerwindowlistener.cpp
+++ b/indra/newview/llviewerwindowlistener.cpp
@@ -20,8 +20,9 @@
 // other Linden headers
 #include "llviewerwindow.h"
 
-LLViewerWindowListener::LLViewerWindowListener(const std::string& pumpname, LLViewerWindow* llviewerwindow):
-    LLDispatchListener(pumpname, "op"),
+LLViewerWindowListener::LLViewerWindowListener(LLViewerWindow* llviewerwindow):
+    LLEventAPI("LLViewerWindow",
+               "LLViewerWindow listener to (e.g.) save a screenshot"),
     mViewerWindow(llviewerwindow)
 {
     // add() every method we want to be able to invoke via this event API.
@@ -34,8 +35,15 @@ LLViewerWindowListener::LLViewerWindowListener(const std::string& pumpname, LLVi
 //  saveSnapshotArgs["showui"] = LLSD::Boolean();
 //  saveSnapshotArgs["rebuild"] = LLSD::Boolean();
 //  saveSnapshotArgs["type"] = LLSD::String();
-    add("saveSnapshot", &LLViewerWindowListener::saveSnapshot, saveSnapshotArgs);
-    add("requestReshape", &LLViewerWindowListener::requestReshape);
+    add("saveSnapshot",
+        "Save screenshot: [\"filename\"], [\"width\"], [\"height\"], [\"showui\"], [\"rebuild\"], [\"type\"]\n"
+        "type: \"COLOR\", \"DEPTH\", \"OBJECT_ID\"\n"
+        "Post on [\"reply\"] an event containing [\"ok\"]",
+        &LLViewerWindowListener::saveSnapshot,
+        saveSnapshotArgs);
+    add("requestReshape",
+        "Resize the window: [\"w\"], [\"h\"]",
+        &LLViewerWindowListener::requestReshape);
 }
 
 void LLViewerWindowListener::saveSnapshot(const LLSD& event) const
diff --git a/indra/newview/llviewerwindowlistener.h b/indra/newview/llviewerwindowlistener.h
index 59c636ecec..699f7907af 100644
--- a/indra/newview/llviewerwindowlistener.h
+++ b/indra/newview/llviewerwindowlistener.h
@@ -12,18 +12,17 @@
 #if ! defined(LL_LLVIEWERWINDOWLISTENER_H)
 #define LL_LLVIEWERWINDOWLISTENER_H
 
-#include "lleventdispatcher.h"
+#include "lleventapi.h"
 
 class LLViewerWindow;
 class LLSD;
 
 /// Listen on an LLEventPump with specified name for LLViewerWindow request events.
-class LLViewerWindowListener: public LLDispatchListener
+class LLViewerWindowListener: public LLEventAPI
 {
 public:
-    /// Specify the pump name on which to listen, and bind the LLViewerWindow
-    /// instance to use (e.g. gViewerWindow).
-    LLViewerWindowListener(const std::string& pumpname, LLViewerWindow* llviewerwindow);
+    /// Bind the LLViewerWindow instance to use (e.g. gViewerWindow).
+    LLViewerWindowListener(LLViewerWindow* llviewerwindow);
 
 private:
     void saveSnapshot(const LLSD& event) const;