Add Doxygen comments

2 files changed, 85 insertions, 13 deletions

diff --git a/indra/media_plugins/base/media_plugin_base.cpp b/indra/media_plugins/base/media_plugin_base.cpp
index 8c8fa24a65..658783e064 100644
--- a/indra/media_plugins/base/media_plugin_base.cpp
+++ b/indra/media_plugins/base/media_plugin_base.cpp
@@ -2,6 +2,8 @@
  * @file media_plugin_base.cpp
  * @brief Media plugin base class for LLMedia API plugin system
  *
+ * All plugins should be a subclass of MediaPluginBase. 
+ *
  * @cond
  * $LicenseInfo:firstyear=2008&license=viewergpl$
  *
@@ -37,7 +39,10 @@
 
 // TODO: Make sure that the only symbol exported from this library is LLPluginInitEntryPoint
 ////////////////////////////////////////////////////////////////////////////////
-//
+/// Media plugin constructor.
+///
+/// @param[in] host_send_func Function for sending messages from plugin to plugin loader shell
+/// @param[in] host_user_data Message data for messages from plugin to plugin loader shell
 
 MediaPluginBase::MediaPluginBase(
 	LLPluginInstance::sendMessageFunction host_send_func,
@@ -55,6 +60,12 @@ MediaPluginBase::MediaPluginBase(
 	mStatus = STATUS_NONE;
 }
 
+/**
+ * Converts current media status enum value into string (STATUS_LOADING into "loading", etc.)
+ * 
+ * @return Media status string ("loading", "playing", "paused", etc)
+ *
+ */
 std::string MediaPluginBase::statusString()
 {
 	std::string result;
@@ -75,6 +86,12 @@ std::string MediaPluginBase::statusString()
 	return result;
 }
 	
+/**
+ * Set media status.
+ * 
+ * @param[in] status Media status (STATUS_LOADING, STATUS_PLAYING, STATUS_PAUSED, etc)
+ *
+ */
 void MediaPluginBase::setStatus(EStatus status)
 {
 	if(mStatus != status)
@@ -85,6 +102,13 @@ void MediaPluginBase::setStatus(EStatus status)
 }
 
 
+/**
+ * Receive message from plugin loader shell.
+ * 
+ * @param[in] message_string Message string
+ * @param[in] user_data Message data
+ *
+ */
 void MediaPluginBase::staticReceiveMessage(const char *message_string, void **user_data)
 {
 	MediaPluginBase *self = (MediaPluginBase*)*user_data;
@@ -102,12 +126,27 @@ void MediaPluginBase::staticReceiveMessage(const char *message_string, void **us
 	}
 }
 
+/**
+ * Send message to plugin loader shell.
+ * 
+ * @param[in] message Message data being sent to plugin loader shell
+ *
+ */
 void MediaPluginBase::sendMessage(const LLPluginMessage &message)
 {
 	std::string output = message.generate();
 	mHostSendFunction(output.c_str(), &mHostUserData);
 }
 
+/**
+ * Notifies plugin loader shell that part of display area needs to be redrawn.
+ * 
+ * @param[in] left Left X coordinate of area to redraw (0,0 is at top left corner)
+ * @param[in] top Top Y coordinate of area to redraw (0,0 is at top left corner)
+ * @param[in] right Right X-coordinate of area to redraw (0,0 is at top left corner)
+ * @param[in] bottom Bottom Y-coordinate of area to redraw (0,0 is at top left corner)
+ *
+ */
 void MediaPluginBase::setDirty(int left, int top, int right, int bottom)
 {
 	LLPluginMessage message(LLPLUGIN_MESSAGE_CLASS_MEDIA, "updated");
@@ -120,6 +159,10 @@ void MediaPluginBase::setDirty(int left, int top, int right, int bottom)
 	sendMessage(message);
 }
 
+/**
+ * Sends "media_status" message to plugin loader shell ("loading", "playing", "paused", etc.)
+ * 
+ */
 void MediaPluginBase::sendStatus()
 {
 	LLPluginMessage message(LLPLUGIN_MESSAGE_CLASS_MEDIA, "media_status");
@@ -143,6 +186,17 @@ extern "C"
 	LLSYMEXPORT int LLPluginInitEntryPoint(LLPluginInstance::sendMessageFunction host_send_func, void *host_user_data, LLPluginInstance::sendMessageFunction *plugin_send_func, void **plugin_user_data);
 }
 
+/**
+ * Plugin initialization and entry point. Establishes communication channel for messages between plugin and plugin loader shell.  TODO:DOC - Please check!
+ * 
+ * @param[in] host_send_func Function for sending messages from plugin to plugin loader shell
+ * @param[in] host_user_data Message data for messages from plugin to plugin loader shell
+ * @param[out] plugin_send_func Function for plugin to receive messages from plugin loader shell
+ * @param[out] plugin_user_data Pointer to plugin instance
+ *
+ * @return int, where 0=success
+ *
+ */
 LLSYMEXPORT int
 LLPluginInitEntryPoint(LLPluginInstance::sendMessageFunction host_send_func, void *host_user_data, LLPluginInstance::sendMessageFunction *plugin_send_func, void **plugin_user_data)
 {
diff --git a/indra/media_plugins/base/media_plugin_base.h b/indra/media_plugins/base/media_plugin_base.h
index 4dd157a07c..8f8e89f2e3 100644
--- a/indra/media_plugins/base/media_plugin_base.h
+++ b/indra/media_plugins/base/media_plugin_base.h
@@ -42,14 +42,17 @@ class MediaPluginBase
 {
 public:
 	MediaPluginBase(LLPluginInstance::sendMessageFunction host_send_func, void *host_user_data);
+   /** Media plugin destructor. */
 	virtual ~MediaPluginBase() {}
 
+   /** Handle received message from plugin loader shell. */
 	virtual void receiveMessage(const char *message_string) = 0;
 	
 	static void staticReceiveMessage(const char *message_string, void **user_data);
 
 protected:
 
+   /** Plugin status. */
 	typedef enum 
 	{
 		STATUS_NONE,
@@ -61,10 +64,13 @@ protected:
 		STATUS_DONE
 	} EStatus;
 
+   /** Plugin shared memory. */
 	class SharedSegmentInfo
 	{
 	public:
+      /** Shared memory address. */
 		void *mAddress;
+      /** Shared memory size. */
 		size_t mSize;
 	};
 
@@ -73,42 +79,54 @@ protected:
 	std::string statusString();
 	void setStatus(EStatus status);		
 	
-	// The quicktime plugin overrides this to add current time and duration to the message...
+	/// Note: The quicktime plugin overrides this to add current time and duration to the message.
 	virtual void setDirty(int left, int top, int right, int bottom);
 
+   /** Map of shared memory names to shared memory. */
 	typedef std::map<std::string, SharedSegmentInfo> SharedSegmentMap;
 
 	
+   /** Function to send message from plugin to plugin loader shell. */
 	LLPluginInstance::sendMessageFunction mHostSendFunction;
+   /** Message data being sent to plugin loader shell by mHostSendFunction. */
 	void *mHostUserData;
+   /** Flag to delete plugin instance (self). */
 	bool mDeleteMe;
+   /** Pixel array to display. TODO:DOC are pixels always 24-bit RGB format, aligned on 32-bit boundary? Also: calling this a pixel array may be misleading since 1 pixel > 1 char. */
 	unsigned char* mPixels;
+   /** TODO:DOC what's this for -- does a texture have its own piece of shared memory? updated on size_change_request, cleared on shm_remove */
 	std::string mTextureSegmentName;
+   /** Width of plugin display in pixels. */
 	int mWidth;
+   /** Height of plugin display in pixels. */
 	int mHeight;
+   /** Width of plugin texture. */
 	int mTextureWidth;
+   /** Height of plugin texture. */
 	int mTextureHeight;
+   /** Pixel depth (pixel size in bytes). */
 	int mDepth;
+   /** Current status of plugin. */
 	EStatus mStatus;
+   /** Map of shared memory segments. */
 	SharedSegmentMap mSharedSegments;
 
 };
 
-// The plugin must define this function to create its instance.
+/** 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
+*/
 int init_media_plugin(
 	LLPluginInstance::sendMessageFunction host_send_func, 
 	void *host_user_data, 
 	LLPluginInstance::sendMessageFunction *plugin_send_func, 
 	void **plugin_user_data);
 
-// It should look something like this:
-/*
-{
-	MediaPluginFoo *self = new MediaPluginFoo(host_send_func, host_user_data);
-	*plugin_send_func = MediaPluginFoo::staticReceiveMessage;
-	*plugin_user_data = (void*)self;
-
-	return 0;
-}
-*/