Add Doxygen comments

3 files changed, 180 insertions, 10 deletions

diff --git a/indra/llplugin/llpluginmessage.cpp b/indra/llplugin/llpluginmessage.cpp
index 34e02c356e..d06f3cefa0 100644
--- a/indra/llplugin/llpluginmessage.cpp
+++ b/indra/llplugin/llpluginmessage.cpp
@@ -37,31 +37,57 @@
 #include "llsdserialize.h"
 #include "u64.h"
 
+/**
+ * Constructor.
+ */
 LLPluginMessage::LLPluginMessage()
 {
 }
 
+/**
+ * Constructor.
+ *
+ * @param[in] p Existing message
+ */
 LLPluginMessage::LLPluginMessage(const LLPluginMessage &p)
 {
 	mMessage = p.mMessage;
 }
 
+/**
+ * Constructor.
+ *
+ * @param[in] message_class Message class
+ * @param[in] message_name Message name
+ */
 LLPluginMessage::LLPluginMessage(const std::string &message_class, const std::string &message_name)
 {
 	setMessage(message_class, message_name);
 }
 
 
+/**
+ * Destructor.
+ */
 LLPluginMessage::~LLPluginMessage()
 {
 }
 
+/**
+ * Reset all internal state.
+ */
 void LLPluginMessage::clear()
 {
 	mMessage = LLSD::emptyMap();
 	mMessage["params"] = LLSD::emptyMap();
 }
 
+/**
+ * Sets the message class and name. Also has the side-effect of clearing any key-value pairs in the message.
+ *
+ * @param[in] message_class Message class
+ * @param[in] message_name Message name
+ */
 void LLPluginMessage::setMessage(const std::string &message_class, const std::string &message_name)
 {
 	clear();
@@ -69,21 +95,45 @@ void LLPluginMessage::setMessage(const std::string &message_class, const std::st
 	mMessage["name"] = message_name;
 }
 
+/**
+ * Sets a key/value pair in the message, where the value is a string.
+ *
+ * @param[in] key Key
+ * @param[in] value String value
+ */
 void LLPluginMessage::setValue(const std::string &key, const std::string &value)
 {
 	mMessage["params"][key] = value;
 }
 
+/**
+ * Sets a key/value pair in the message, where the value is LLSD.
+ *
+ * @param[in] key Key
+ * @param[in] value LLSD value
+ */
 void LLPluginMessage::setValueLLSD(const std::string &key, const LLSD &value)
 {
 	mMessage["params"][key] = value;
 }
 
+/**
+ * Sets a key/value pair in the message, where the value is signed 32-bit.
+ *
+ * @param[in] key Key
+ * @param[in] value 32-bit signed value
+ */
 void LLPluginMessage::setValueS32(const std::string &key, S32 value)
 {
 	mMessage["params"][key] = value;
 }
 
+/**
+ * Sets a key/value pair in the message, where the value is unsigned 32-bit. The value is stored as a string beginning with "0x".
+ *
+ * @param[in] key Key
+ * @param[in] value 32-bit unsigned value
+ */
 void LLPluginMessage::setValueU32(const std::string &key, U32 value)
 {
 	std::stringstream temp;
@@ -91,16 +141,34 @@ void LLPluginMessage::setValueU32(const std::string &key, U32 value)
 	setValue(key, temp.str());
 }
 
+/**
+ * Sets a key/value pair in the message, where the value is a bool.
+ *
+ * @param[in] key Key
+ * @param[in] value Boolean value
+ */
 void LLPluginMessage::setValueBoolean(const std::string &key, bool value)
 {
 	mMessage["params"][key] = value;
 }
 
+/**
+ * Sets a key/value pair in the message, where the value is a double.
+ *
+ * @param[in] key Key
+ * @param[in] value Boolean value
+ */
 void LLPluginMessage::setValueReal(const std::string &key, F64 value)
 {
 	mMessage["params"][key] = value;
 }
 
+/**
+ * Sets a key/value pair in the message, where the value is a pointer. The pointer is stored as a string.
+ *
+ * @param[in] key Key
+ * @param[in] value Pointer value
+ */
 void LLPluginMessage::setValuePointer(const std::string &key, void* value)
 {
 	std::stringstream temp;
@@ -109,16 +177,33 @@ void LLPluginMessage::setValuePointer(const std::string &key, void* value)
 	setValue(key, temp.str());
 }
 
+/**
+ * Gets the message class.
+ *
+ * @return Message class
+ */
 std::string LLPluginMessage::getClass(void) const
 {
 	return mMessage["class"];
 }
 
+/**
+ * Gets the message name.
+ *
+ * @return Message name
+ */
 std::string LLPluginMessage::getName(void) const
 {
 	return mMessage["name"];
 }
 
+/**
+ *	Returns true if the specified key exists in this message (useful for optional parameters).
+ *
+ * @param[in] key Key
+ *
+ * @return True if key exists, false otherwise.
+ */
 bool LLPluginMessage::hasValue(const std::string &key) const
 {
 	bool result = false;
@@ -131,6 +216,13 @@ bool LLPluginMessage::hasValue(const std::string &key) const
 	return result;
 }
 
+/**
+ *	Gets the value of a key as a string. If the key does not exist, an empty string will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return String value of key if key exists, empty string if key does not exist.
+ */
 std::string LLPluginMessage::getValue(const std::string &key) const
 {
 	std::string result;
@@ -143,6 +235,13 @@ std::string LLPluginMessage::getValue(const std::string &key) const
 	return result;
 }
 
+/**
+ *	Gets the value of a key as LLSD. If the key does not exist, a null LLSD will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return LLSD value of key if key exists, null LLSD if key does not exist.
+ */
 LLSD LLPluginMessage::getValueLLSD(const std::string &key) const
 {
 	LLSD result;
@@ -155,6 +254,13 @@ LLSD LLPluginMessage::getValueLLSD(const std::string &key) const
 	return result;
 }
 
+/**
+ *	Gets the value of a key as signed 32-bit int. If the key does not exist, 0 will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Signed 32-bit int value of key if key exists, 0 if key does not exist.
+ */
 S32 LLPluginMessage::getValueS32(const std::string &key) const
 {
 	S32 result = 0;
@@ -167,6 +273,13 @@ S32 LLPluginMessage::getValueS32(const std::string &key) const
 	return result;
 }
 
+/**
+ *	Gets the value of a key as unsigned 32-bit int. If the key does not exist, 0 will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Unsigned 32-bit int value of key if key exists, 0 if key does not exist.
+ */
 U32 LLPluginMessage::getValueU32(const std::string &key) const
 {
 	U32 result = 0;
@@ -181,6 +294,13 @@ U32 LLPluginMessage::getValueU32(const std::string &key) const
 	return result;
 }
 
+/**
+ *	Gets the value of a key as a bool. If the key does not exist, false will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Boolean value of key if it exists, false otherwise.
+ */
 bool LLPluginMessage::getValueBoolean(const std::string &key) const
 {
 	bool result = false;
@@ -193,6 +313,13 @@ bool LLPluginMessage::getValueBoolean(const std::string &key) const
 	return result;
 }
 
+/**
+ *	Gets the value of a key as a double. If the key does not exist, 0 will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Value as a double if key exists, 0 otherwise.
+ */
 F64 LLPluginMessage::getValueReal(const std::string &key) const
 {
 	F64 result = 0.0f;
@@ -205,6 +332,13 @@ F64 LLPluginMessage::getValueReal(const std::string &key) const
 	return result;
 }
 
+/**
+ *	Gets the value of a key as a pointer. If the key does not exist, NULL will be returned.
+ *
+ * @param[in] key Key
+ *
+ * @return Pointer value if key exists, NULL otherwise.
+ */
 void* LLPluginMessage::getValuePointer(const std::string &key) const
 {
 	void* result = NULL;
@@ -219,6 +353,11 @@ void* LLPluginMessage::getValuePointer(const std::string &key) const
 	return result;
 }
 
+/**
+ *	Flatten the message into a string.
+ *
+ * @return Message as a string.
+ */
 std::string LLPluginMessage::generate(void) const
 {
 	std::ostringstream result;
@@ -230,7 +369,11 @@ std::string LLPluginMessage::generate(void) const
 	return result.str();
 }
 
-
+/**
+ *	Parse an incoming message into component parts. Clears all existing state before starting the parse.
+ *
+ * @return Returns -1 on failure, otherwise returns the number of key/value pairs in the incoming message.
+ */
 int LLPluginMessage::parse(const std::string &message)
 {
 	// clear any previous state
@@ -255,16 +398,31 @@ LLPluginMessageDispatcher::~LLPluginMessageDispatcher()
 	
 }
 	
+/**
+ * Add a message listener. TODO:DOC need more info on what uses this. when are multiple listeners needed?
+ *
+ * @param[in] listener Message listener
+ */
 void LLPluginMessageDispatcher::addPluginMessageListener(LLPluginMessageListener *listener)
 {
 	mListeners.insert(listener);
 }
 
+/**
+ * Remove a message listener.
+ *
+ * @param[in] listener Message listener
+ */
 void LLPluginMessageDispatcher::removePluginMessageListener(LLPluginMessageListener *listener)
 {
 	mListeners.erase(listener);
 }
 
+/**
+ * Distribute a message to all message listeners.
+ *
+ * @param[in] message Message
+ */
 void LLPluginMessageDispatcher::dispatchPluginMessage(const LLPluginMessage &message)
 {
 	for (listener_set_t::iterator it = mListeners.begin();
diff --git a/indra/llplugin/llpluginmessage.h b/indra/llplugin/llpluginmessage.h
index 99f8d1194f..e00022a245 100644
--- a/indra/llplugin/llpluginmessage.h
+++ b/indra/llplugin/llpluginmessage.h
@@ -104,6 +104,9 @@ private:
 
 };
 
+/**
+ * @brief Listens for plugin messages.
+ */
 class LLPluginMessageListener
 {
 public:
@@ -112,6 +115,11 @@ public:
 	
 };
 
+/**
+ * @brief Dispatcher for plugin messages.
+ *
+ * Manages the set of plugin message listeners and distributes messages to plugin message listeners.
+ */
 class LLPluginMessageDispatcher
 {
 public:
@@ -122,7 +130,9 @@ public:
 protected:
 	void dispatchPluginMessage(const LLPluginMessage &message);
 
+   /** A set of message listeners. */
 	typedef std::set<LLPluginMessageListener*> listener_set_t;
+   /** The set of message listeners. */
 	listener_set_t mListeners;
 };
 
diff --git a/indra/media_plugins/base/media_plugin_base.h b/indra/media_plugins/base/media_plugin_base.h
index 8f8e89f2e3..ed4dc0cfa9 100644
--- a/indra/media_plugins/base/media_plugin_base.h
+++ b/indra/media_plugins/base/media_plugin_base.h
@@ -114,15 +114,17 @@ protected:
 };
 
 /** The plugin <b>must</b> define this function to create its instance.
- * It should look something like this: \n
-{  \n
-   MediaPluginFoo *self = new MediaPluginFoo(host_send_func, host_user_data); \n
-   *plugin_send_func = MediaPluginFoo::staticReceiveMessage; \n
-   *plugin_user_data = (void*)self; \n
-   \n
-   return 0; \n
-}  \n
-*/
+ * It should look something like this: 
+ * @code
+ * {  
+ *    MediaPluginFoo *self = new MediaPluginFoo(host_send_func, host_user_data); 
+ *    *plugin_send_func = MediaPluginFoo::staticReceiveMessage; 
+ *    *plugin_user_data = (void*)self; 
+ *    
+ *    return 0; 
+ * }  
+ * @endcode
+ */
 int init_media_plugin(
 	LLPluginInstance::sendMessageFunction host_send_func, 
 	void *host_user_data,