merge

--HG--
branch : avatar-pipeline

4 files changed, 62 insertions, 9 deletions

diff --git a/indra/llplugin/llplugininstance.cpp b/indra/llplugin/llplugininstance.cpp
index 16ba492669..44e3b4950f 100644
--- a/indra/llplugin/llplugininstance.cpp
+++ b/indra/llplugin/llplugininstance.cpp
@@ -37,13 +37,21 @@
 
 #include "llapr.h"
 
-//virtual 
+/** Virtual destructor. */
 LLPluginInstanceMessageListener::~LLPluginInstanceMessageListener()
 {
 }
 
+/** 
+ * TODO:DOC describe how it's used
+ */
 const char *LLPluginInstance::PLUGIN_INIT_FUNCTION_NAME = "LLPluginInitEntryPoint";
 
+/** 
+ * Constructor.
+ *
+ * @param[in] owner Plugin instance. TODO:DOC is this a good description of what "owner" is?
+ */
 LLPluginInstance::LLPluginInstance(LLPluginInstanceMessageListener *owner) :
 	mDSOHandle(NULL),
 	mPluginUserData(NULL),
@@ -52,6 +60,9 @@ LLPluginInstance::LLPluginInstance(LLPluginInstanceMessageListener *owner) :
 	mOwner = owner;
 }
 
+/** 
+ * Destructor.
+ */
 LLPluginInstance::~LLPluginInstance()
 {
 	if(mDSOHandle != NULL)
@@ -61,6 +72,12 @@ LLPluginInstance::~LLPluginInstance()
 	}
 }
 
+/** 
+ * Dynamically loads the plugin and runs the plugin's init function.
+ *
+ * @param[in] plugin_file Name of plugin dll/dylib/so. TODO:DOC is this correct? see .h
+ * @return 0 if successful, APR error code or error code from the plugin's init function on failure.
+ */
 int LLPluginInstance::load(std::string &plugin_file)
 {
 	pluginInitFunction init_function = NULL;
@@ -102,6 +119,11 @@ int LLPluginInstance::load(std::string &plugin_file)
 	return (int)result;
 }
 
+/** 
+ * Sends a message to the plugin.
+ *
+ * @param[in] message Message
+ */
 void LLPluginInstance::sendMessage(const std::string &message)
 {
 	if(mPluginSendMessageFunction)
@@ -115,6 +137,10 @@ void LLPluginInstance::sendMessage(const std::string &message)
 	}
 }
 
+/**
+ * Idle. TODO:DOC what's the purpose of this?
+ *
+ */
 void LLPluginInstance::idle(void)
 {
 }
@@ -128,6 +154,11 @@ void LLPluginInstance::staticReceiveMessage(const char *message_string, void **u
 	self->receiveMessage(message_string);
 }
 
+/**
+ * Plugin receives message from plugin loader shell.
+ *
+ * @param[in] message_string Message
+ */
 void LLPluginInstance::receiveMessage(const char *message_string)
 {
 	if(mOwner)
diff --git a/indra/llplugin/llplugininstance.h b/indra/llplugin/llplugininstance.h
index 02936f65fb..c11d5ab5d4 100644
--- a/indra/llplugin/llplugininstance.h
+++ b/indra/llplugin/llplugininstance.h
@@ -1,6 +1,5 @@
 /** 
  * @file llplugininstance.h
- * @brief LLPluginInstance handles loading the dynamic library of a plugin and setting up its entry points for message passing.
  *
  * @cond
  * $LicenseInfo:firstyear=2008&license=viewergpl$
@@ -39,13 +38,20 @@
 
 #include "apr_dso.h"
 
+/**
+ * @brief LLPluginInstanceMessageListener receives messages sent from the plugin loader shell to the plugin.
+ */
 class LLPluginInstanceMessageListener
 {
 public:
 	virtual ~LLPluginInstanceMessageListener();
+   /** Plugin receives message from plugin loader shell. */
 	virtual void receivePluginMessage(const std::string &message) = 0;
 };
 
+/**
+ * @brief LLPluginInstance handles loading the dynamic library of a plugin and setting up its entry points for message passing.
+ */
 class LLPluginInstance
 {
 	LOG_CLASS(LLPluginInstance);
@@ -60,19 +66,27 @@ public:
 	// Sends a message to the plugin.
 	void sendMessage(const std::string &message);
 	
+   // TODO:DOC is this comment obsolete? can't find "send_count" anywhere in indra tree.
 	// send_count is the maximum number of message to process from the send queue.  If negative, it will drain the queue completely.
 	// The receive queue is always drained completely.
 	// Returns the total number of messages processed from both queues.
 	void idle(void);
 	
-	// this is the signature of the "send a message" function.  
-	// message_string is a null-terminated C string
-	// user_data is the opaque reference that the callee supplied during setup.
+	/** The signature of the function for sending a message from plugin to plugin loader shell.
+    *
+	 * @param[in] message_string Null-terminated C string 
+    * @param[in] user_data The opaque reference that the callee supplied during setup.
+    */
 	typedef void (*sendMessageFunction) (const char *message_string, void **user_data);
 
-	// signature of the plugin init function
+	/** The signature of the plugin init function. TODO:DOC check direction (pluging loader shell to plugin?)
+    *
+    * @param[in] host_user_data Data from plugin loader shell.
+    * @param[in] plugin_send_function Function for sending from the plugin loader shell to plugin.
+    */
 	typedef int (*pluginInitFunction) (sendMessageFunction host_send_func, void *host_user_data, sendMessageFunction *plugin_send_func, void **plugin_user_data);
 	
+   /** Name of plugin init function */
 	static const char *PLUGIN_INIT_FUNCTION_NAME;
 	
 private:
diff --git a/indra/llplugin/llpluginmessage.cpp b/indra/llplugin/llpluginmessage.cpp
index d06f3cefa0..f76d848a70 100644
--- a/indra/llplugin/llpluginmessage.cpp
+++ b/indra/llplugin/llpluginmessage.cpp
@@ -387,12 +387,18 @@ int LLPluginMessage::parse(const std::string &message)
 }
 
 
+/**
+ * Destructor
+ */
 LLPluginMessageListener::~LLPluginMessageListener()
 {
 	// TODO: should listeners have a way to ensure they're removed from dispatcher lists when deleted?
 }
 
 
+/**
+ * Destructor
+ */
 LLPluginMessageDispatcher::~LLPluginMessageDispatcher()
 {
 	
diff --git a/indra/llplugin/llpluginmessage.h b/indra/llplugin/llpluginmessage.h
index e00022a245..cbd31e0964 100644
--- a/indra/llplugin/llpluginmessage.h
+++ b/indra/llplugin/llpluginmessage.h
@@ -1,6 +1,5 @@
 /** 
  * @file llpluginmessage.h
- * @brief LLPluginMessage encapsulates the serialization/deserialization of messages passed to and from plugins.
  *
  * @cond
  * $LicenseInfo:firstyear=2008&license=viewergpl$
@@ -36,7 +35,9 @@
 
 #include "llsd.h"
 
-
+/**
+ * @brief LLPluginMessage encapsulates the serialization/deserialization of messages passed to and from plugins.
+ */
 class LLPluginMessage
 {
 	LOG_CLASS(LLPluginMessage);
@@ -105,12 +106,13 @@ private:
 };
 
 /**
- * @brief Listens for plugin messages.
+ * @brief Listener for plugin messages.
  */
 class LLPluginMessageListener
 {
 public:
 	virtual ~LLPluginMessageListener();
+   /** Plugin receives message from plugin loader shell. */
 	virtual void receivePluginMessage(const LLPluginMessage &message) = 0;
 	
 };