]> git.ipfire.org Git - thirdparty/open-vm-tools.git/commitdiff
Unity: Reformat incomplete, unused plugin Doxygen comments as VMW style.
authorVMware, Inc <>
Mon, 20 Dec 2010 21:39:19 +0000 (13:39 -0800)
committerMarcelo Vanzin <mvanzin@vmware.com>
Mon, 20 Dec 2010 21:39:19 +0000 (13:39 -0800)
Signed-off-by: Marcelo Vanzin <mvanzin@vmware.com>
open-vm-tools/services/plugins/unity/ghiTclo.cpp
open-vm-tools/services/plugins/unity/unityPlugin.cpp
open-vm-tools/services/plugins/unity/unityPlugin.h
open-vm-tools/services/plugins/unity/unityPluginEntry.cpp

index 931171a53f4397901d7a7b216890ee1f5293d3c5..d17d1f1a240a290843dbb579c2ea8752bf720bdc 100644 (file)
@@ -1196,17 +1196,24 @@ GHITcloRestoreOutlookTempFolder(RpcInData *data) // IN/OUT: RPC data
 }
 
 
-/**
- * @brief Wrapper function for the ghi.guest.trashFolder.action RPC.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * GHITcloTrashFolderAction --
  *
- * params[in] data Pointer to the RpcInData structure for the RPC.
+ *      Wrapper function for the ghi.guest.trashFolder.action RPC.
+ *
+ * Results:
+ *      TRUE on success, FALSE on failure.
  *
- * @retval TRUE  The RPC succeeded.
- * @retval FALSE The RPC failed.
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 gboolean
-GHITcloTrashFolderAction(RpcInData *data)
+GHITcloTrashFolderAction(RpcInData *data)       // IN/OUT:
 {
    Bool ret = FALSE;
 
@@ -1248,22 +1255,28 @@ GHITcloTrashFolderAction(RpcInData *data)
 }
 
 
-/**
- * @brief Send the ghi.guest.trashFolder.state RPC to the host.
+/*
+ *-----------------------------------------------------------------------------
  *
- * Send the ghi.guest.trashFolder.state RPC to the host. This function is used
- * by the platform-specific GHI backends to notify the host when the state of
- * the Trash (aka Recycle Bin) folder changes. Currently, the only information
- * sent using this RPC is the empty/non-empty state of the Trash folder.
+ * GHISendTrashFolderStateRPC --
  *
- * @params[in] empty True if the trash folder is empty.
+ *      Send the ghi.guest.trashFolder.state RPC to the host. This function is
+ *      used by the platform-specific GHI backends to notify the host when the
+ *      state of the Trash (aka Recycle Bin) folder changes. Currently, the only
+ *      information sent using this RPC is the empty/non-empty state of the
+ *      Trash folder.
  *
- * @retval TRUE  The RPC was sent successfully.
- * @retval FALSE The RPC was not sent.
+ * Results:
+ *      TRUE if RPC was sent successfully, FALSE otherwise.
+ *
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 Bool
-GHISendTrashFolderStateRPC(Bool empty)
+GHISendTrashFolderStateRPC(Bool empty)  // IN: TRUE if the trash folder is empty.
 {
    Bool ret = FALSE;
    DynBuf outBuf;
@@ -1339,20 +1352,24 @@ exit:
 }
 
 
-/**
- * @brief Return the icon for the Trash folder (aka Recycle Bin) to the host.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * GHITcloTrashFolderGetIcon --
  *
- * Get the icon for the Trash Folder (aka Recycle Bin) and return it to the
- * host.
+ *      Return the icon for the Trash folder (aka Recycle Bin) to the host.
  *
- * @param[in] data Pointer to the RpcInData structure for the RPC.
+ * Results:
+ *      TRUE on success, FALSE on failure.
  *
- * @retval TRUE  The RPC succeeded.
- * @retval FALSE The RPC failed.
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 gboolean
-GHITcloTrashFolderGetIcon(RpcInData *data)
+GHITcloTrashFolderGetIcon(RpcInData *data) // IN/OUT:
 {
    Bool ret = FALSE;
 
@@ -1389,17 +1406,24 @@ exit:
 }
 
 
-/**
- * @brief Send a mouse or keyboard event to a tray icon.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * GHITcloTrayIconSendEvent --
  *
- * @param[in] data Pointer to the RpcInData structure for the RPC.
+ *      Send a mouse or keyboard event to a tray icon.
  *
- * @retval TRUE  The RPC succeeded.
- * @retval FALSE The RPC failed.
+ * Results:
+ *      TRUE on success, FALSE on failure.
+ *
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 gboolean
-GHITcloTrayIconSendEvent(RpcInData *data)
+GHITcloTrayIconSendEvent(RpcInData *data) // IN/OUT: XXX
 {
    Bool ret = FALSE;
    GHITrayIconEventV1 *v1ptr = NULL;
@@ -1460,17 +1484,25 @@ exit:
    return ret;
 }
 
-/**
- * @brief Start sending tray icon updates to the VMX.
+
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * GHITclOTrayIconStartUpdates --
+ *
+ *      Start sending tray icon updates to the VMX.
+ *
+ * Results:
+ *      TRUE on success, FALSE on failure.
  *
- * @param[in] data Pointer to the RpcInData structure for the RPC.
+ * Side effects:
+ *      XXX.
  *
- * @retval TRUE  The RPC succeeded.
- * @retval FALSE The RPC failed.
+ *-----------------------------------------------------------------------------
  */
 
 gboolean
-GHITcloTrayIconStartUpdates(RpcInData *data)
+GHITcloTrayIconStartUpdates(RpcInData *data) // IN/OUT: XXX
 {
    Bool ret = FALSE;
 
@@ -1504,17 +1536,25 @@ exit:
    return ret;
 }
 
-/**
- * @brief Stop sending tray icon updates to the VMX.
+
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * GHITcloTrayIconStopUpdates --
+ *
+ *      Stop sending tray icon updates to the VMX.
+ *
+ * Results:
+ *      TRUE on success, FALSE on failure.
  *
- * @param[in] data Pointer to the RpcInData structure for the RPC.
+ * Side effects:
+ *      XXX.
  *
- * @retval TRUE  The RPC succeeded.
- * @retval FALSE The RPC failed.
+ *-----------------------------------------------------------------------------
  */
 
 gboolean
-GHITcloTrayIconStopUpdates(RpcInData *data)
+GHITcloTrayIconStopUpdates(RpcInData *data) // IN/OUT:
 {
    Bool ret = FALSE;
 
@@ -1548,17 +1588,24 @@ exit:
 }
 
 
-/**
- * @brief Send the ghi.guest.trayIcon.update RPC to the host.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * GHISendTrayIconUpdateRPC --
  *
- * @param[in] data Pointer to the RpcInData structure for the RPC.
+ *      Send the ghi.guest.trayIcon.update RPC to the host.
  *
- * @retval TRUE  The RPC succeeded.
- * @retval FALSE The RPC failed.
+ * Results:
+ *      TRUE if sent, FALSE otherwise.
+ *
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 Bool
-GHISendTrayIconUpdateRpc(XDR *xdrs)
+GHISendTrayIconUpdateRpc(XDR *xdrs) // XXX
 {
    Bool ret = FALSE;
    DynBuf outBuf;
@@ -1611,14 +1658,21 @@ exit:
 }
 
 
-/**
- * @brief Set the specified window to be focused (NULL or zero window ID indicates
- * that no window should be focused).
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * GHITcloSetFocusedWindow --
+ *
+ *      Set the specified window to be focused (NULL or zero window ID indicates
+ *      that no window should be focused).
  *
- * @param[in] data Pointer to the RpcInData structure for the RPC.
+ * Results:
+ *      TRUE on success, FALSE otherwise.
+ *
+ * Side effects:
+ *      XXX.
  *
- * @retval TRUE  The RPC succeeded.
- * @retval FALSE The RPC failed.
+ *-----------------------------------------------------------------------------
  */
 
 gboolean
@@ -1685,18 +1739,25 @@ exit:
 }
 
 
-/**
- * @brief Get the hash (or timestamp) of information returned by
- * GHITcloGetBinaryInfo.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * GHITcloGetExecInfoHash --
+ *
+ *      Get the hash (or timestamp) of information returned by
+ *      GHITcloGetBinaryInfo.
  *
- * @param[in] data Pointer to the RpcInData structure for the RPC.
+ * Results:
+ *      TRUE on success, FALSE on failure.
+ *
+ * Side effects:
+ *      None.
  *
- * @retval TRUE  The RPC succeeded.
- * @retval FALSE The RPC failed.
+ *-----------------------------------------------------------------------------
  */
 
 gboolean
-GHITcloGetExecInfoHash(RpcInData *data)
+GHITcloGetExecInfoHash(RpcInData *data) // IN/OUT:
 {
    Bool ret = TRUE;
    GHIGetExecInfoHashRequest requestMsg;
index b5b41046caf82c43cb4f555f12861e3696ee3481..5dea02bbb404159f6edda565f0edc0b952a911ad 100644 (file)
  *
  *********************************************************/
 
-/**
- * @file unityPlugin.cpp
+/*
+ * unityPlugin.cpp --
  *
- *    Implements an object that provides the entry points for tools unity plugin.
+ *      Implements an object that provides the entry points for tools unity
+ *      plugin.
  */
 
 #include "vmware/tools/plugin.h"
@@ -33,11 +34,11 @@ extern "C" {
    #include "guestrpc/unityActive.h"
    #include "rpcin.h"
    #include "strutil.h"
-#if defined(OPEN_VM_TOOLS)
-   #include "unitylib/unity.h"
-#else
-   #include "unity.h"
-#endif // OPEN_VM_TOOLS
+   #if defined(OPEN_VM_TOOLS)
+      #include "unitylib/unity.h"
+   #else
+      #include "unity.h"
+   #endif // OPEN_VM_TOOLS
    #include "xdrutil.h"
 };
 
@@ -62,25 +63,48 @@ namespace vmware { namespace tools {
 static NotifyIconRpcCallback gNotifyIconCallback;
 #endif // G_PLATFORM_WIN32
 
-/**
- * Constructor for the Unity plugin, initialized Unity, and common options values
+
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * UnityPlugin::UnityPlugin --
+ *
+ *      Constructor for the Unity plugin, initialized Unity, and common options
+ *      values.
+ *
+ * Results:
+ *      None.
+ *
+ * Side effects:
+ *      None.
  *
+ *-----------------------------------------------------------------------------
  */
 
 UnityPlugin::UnityPlugin() : mUnityUpdateChannel(NULL)
 {
 }
 
-/**
- * Initializer for the Unity plugin, initialized Unity, and common options values
+
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * UnityPlugin::Initialize --
+ *
+ *      Initializer for the Unity plugin, initialized Unity, and common options
+ *      values
  *
- * @param[in]  ctx      Host application context.
+ * Results:
+ *      True if initializatino was successful.
  *
- * @return true if initialization was successful.
+ * Side effects:
+ *      None.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 gboolean
-UnityPlugin::Initialize(ToolsAppCtx *ctx)
+UnityPlugin::Initialize(ToolsAppCtx *ctx)       // IN: Host application context.
 {
    ASSERT(ctx);
 
@@ -142,8 +166,20 @@ UnityPlugin::Initialize(ToolsAppCtx *ctx)
 }
 
 
-/**
- * Destructor for the Unity plugin, cleanup Unity
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * UnityPlugin::~UnityPlugin --
+ *
+ *      Destructor for the Unity plugin, cleanup Unity.
+ *
+ * Results:
+ *      None.
+ *
+ * Side effects:
+ *      Whole lotta stuff.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 UnityPlugin::~UnityPlugin()
@@ -158,21 +194,33 @@ UnityPlugin::~UnityPlugin()
    GHITcloCleanup();
 }
 
-/**
- * Called by the service core when the host requests the capabilities supported
- * by the guest tools.
+
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * UnityPlugin::GetCapabilities --
+ *
+ *      Called by the service core when the host requests the capabilities
+ *      supported by the guest tools.
  *
- * @param[in]  set      Whether capabilities are being set or unset.
+ * Results:
+ *      A list of capabilities to be sent to the host.
  *
- * @return A list of capabilities to be sent to the host.
+ * Side effects:
+ *      None.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 std::vector<ToolsAppCapability>
-UnityPlugin::GetCapabilities(gboolean set)
+UnityPlugin::GetCapabilities(gboolean set) // IN: Whether capabilities are being
+                                           // set or unset.
+                                           // XXX UNUSED  Fix this or mark as such.
 {
    std::vector<ToolsAppCapability> capsVector;
 
-   /* We can't use UNITY_RPC_UNITY_CAP here because that define includes the
+   /*
+    * We can't use UNITY_RPC_UNITY_CAP here because that define includes the
     * tools.capability prefix which CoreServices will automatically prepend to the
     * supplied name.
     */
@@ -184,11 +232,21 @@ UnityPlugin::GetCapabilities(gboolean set)
 }
 
 
-/**
- * Called by the service core when the host requests the RPCs supported
- * by the guest tools.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * UnityPlugin::GetRpcCallbackList --
+ *
+ *      Called by the service core when the host requests the RPCs supported
+ *      by the guest tools.
+ *
+ * Results:
+ *      A list of RPC Callbacks to be sent to the host.
+ *
+ * Side effects:
+ *      None.
  *
- * @return A list of RPC Callbacks to be sent to the host.
+ *-----------------------------------------------------------------------------
  */
 
 std::vector<RpcChannelCallback>
index 7462d9e3ca82ef239a1bfd512e9f3ca18eea95f8..f90ceb9d434198762419d18ac3be250b22bd7b77 100644 (file)
  *
  *********************************************************/
 
-#ifndef _UNITY_PLUGIN_H_
-#define _UNITY_PLUGIN_H_
-
-/**
- * @file unityPlugin.h
- *
- *    Defines the object that implements the tools core service plugin form of Unity.
+/*
+ * unityPlugin.h --
  *
- * @addtogroup vmtools_plugins
- * @{
+ *    Defines the object that implements the tools core service plugin form of
+ *    Unity.
  */
 
+#ifndef _UNITY_PLUGIN_H_
+#define _UNITY_PLUGIN_H_
+
 #include <string>
 #include <vector>
 
@@ -44,16 +42,20 @@ class UnityPBRPCServer;
 typedef struct _UnityUpdateChannel UnityUpdateChannel;
 
 
-/**
- * Helper struct to build an RPCChannelCallback structure from a name and a
- * simple function pointer that takes an RPCInData pointer.
+/*
+ *-----------------------------------------------------------------------------
  *
- * @param[in]  RpcName   RPC Name.
- * @param[in]  func      RPC Callback Function Pointer.
+ * vmware::tools::RpcChannelCallbackEntry --
  *
+ *      Helper struct to build an RPCChannelCallback structure from a command
+ *      string and RpcIn_Callback.
+ *
+ *-----------------------------------------------------------------------------
  */
 
-struct RpcChannelCallbackEntry  : public RpcChannelCallback {
+struct RpcChannelCallbackEntry
+   : public RpcChannelCallback
+{
    RpcChannelCallbackEntry(const char *RpcName, RpcIn_Callback func)
    {
       name = RpcName;
@@ -66,16 +68,21 @@ struct RpcChannelCallbackEntry  : public RpcChannelCallback {
 };
 
 
-/**
- * Helper struct to build an ToolsAppCapability structure from an old style
- * capability name and flag to indicate whether the capability is enabled.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * vmware::tools::ToolsAppCapabilityOldEntry --
  *
- * @param[in]  capName   Old style capabilty name.
- * @param[in]  enabled   True if the capability is enabled.
+ *      Helper struct to build an ToolsAppCapability structure from an old
+ *      style capability name and flag to indicate whether the capability is
+ *      enabled.
  *
+ *-----------------------------------------------------------------------------
  */
 
-struct ToolsAppCapabilityOldEntry : public ToolsAppCapability {
+struct ToolsAppCapabilityOldEntry
+   : public ToolsAppCapability
+{
    ToolsAppCapabilityOldEntry(const char *capName, gboolean enabled)
    {
       type = TOOLS_CAP_OLD;
@@ -88,16 +95,20 @@ struct ToolsAppCapabilityOldEntry : public ToolsAppCapability {
 };
 
 
-/**
- * Helper struct to build an ToolsAppCapability structure from a new style
- * capability index and flag to indicate whether the capability is enabled.
+/*
+ *-----------------------------------------------------------------------------
  *
- * @param[in]  cap       GuestCapabilities index.
- * @param[in]  enabled   True if the capability is enabled.
+ * vmware::tools::ToolsAppCapabilityNewEntry --
  *
+ *      Helper struct to build an ToolsAppCapability structure from a new style
+ *      capability index and flag to indicate whether the capability is enabled.
+ *
+ *-----------------------------------------------------------------------------
  */
 
-struct ToolsAppCapabilityNewEntry : public ToolsAppCapability {
+struct ToolsAppCapabilityNewEntry
+   : public ToolsAppCapability
+{
    ToolsAppCapabilityNewEntry(GuestCapabilities cap, gboolean enabled)
    {
       type = TOOLS_CAP_NEW;
@@ -108,100 +119,40 @@ struct ToolsAppCapabilityNewEntry : public ToolsAppCapability {
 };
 
 
-/**
- * Defines a pure virtual interface for plugins to implement. These methods
- * are called by per-plugin static C functions in the the plugin entry module.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * vmware::tools::ToolsPlugin --
+ *
+ *      Defines a pure virtual interface for plugins to implement. These
+ *      methods are called by per-plugin static C functions in the the plugin
+ *      entry module.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 class ToolsPlugin {
 public:
    virtual ~ToolsPlugin() {};
 
-
-   /**
-    * Initializer for the plugin.
-    *
-    * @param[in]  ctx      Host application context.
-    *
-    * @return true if initialization was successful.
-    */
    virtual gboolean Initialize(ToolsAppCtx *ctx) = 0;
-
-   /**
-    * Handles a reset signal. This callback is called when the service receives a
-    * "reset" message from the VMX, meaning the VMX may be restarting the RPC
-    * channel (due, for example, to restoring a snapshot, resuming a VM or a VMotion),
-    * and should be used to reset any plugin state that depends on the VMX.
-    *
-    * @param[in]  src      Event source.
-    *
-    * @return TRUE on success.
-    */
-
    virtual gboolean Reset(gpointer src) = 0;
-
-   /**
-    * Handles a shutdown callback; This is called before the service is shut down,
-    * and should be used to clean up any resources that were initialized by the plugin.
-    *
-    * @param[in]  src      The source object.
-    */
-
    virtual void Shutdown(gpointer src) = 0;
-
-   /**
-    * Handles a "Set_Option" callback. This callback is called when the VMX sends
-    * a "Set_Option" command to tools, to configure different options whose values
-    * are kept outside of the virtual machine.
-    *
-    * @param[in]  src      Event source.
-    * @param[in]  option   Option being set.
-    * @param[in]  value    Option value.
-    *
-    * @return TRUE on success.
-    */
-
    virtual gboolean SetOption(gpointer src,
                               const std::string &option,
                               const std::string &value) = 0;
-
-   /**
-    * Called by the service core when the host requests the capabilities supported
-    * by the guest tools.
-    *
-    * @param[in]  set      Whether capabilities are being set or unset.
-    *
-    * @return A list of capabilities to be sent to the host.
-    */
-
    virtual std::vector<ToolsAppCapability> GetCapabilities(gboolean set) = 0;
-
-   /**
-    * Called by the service core when the host requests the RPCs supported
-    * by the guest tools.
-    *
-    * @return A list of RPC Callbacks to be sent to the host.
-    */
-
    virtual std::vector<RpcChannelCallback> GetRpcCallbackList() = 0;
 
 #if defined(G_PLATFORM_WIN32)
-   /**
-    * Handles a session state change callback; this is only called on Windows,
-    * from both the "vmsvc" instance (handled by SCM notifications) and from
-    * "vmusr" with the "fast user switch" plugin.
-    *
-    * @param[in]  src         The source object.
-    * @param[in]  stateCode   Session state change code.
-    * @param[in]  sessionID   Session ID.
-    */
-
    virtual void SessionChange(gpointer src, DWORD stateCode, DWORD sessionID) = 0;
 #endif // G_PLATFORM_WIN32
 };
 
 
-class UnityPlugin  : public ToolsPlugin {
+class UnityPlugin
+   : public ToolsPlugin
+{
 public:
    UnityPlugin();
    virtual ~UnityPlugin();
@@ -210,7 +161,9 @@ public:
 
    virtual gboolean Reset(gpointer src) { return TRUE; }
    virtual void Shutdown(gpointer src) {};
-   virtual gboolean SetOption(gpointer src, const std::string &option, const std::string &value)
+   virtual gboolean SetOption(gpointer src,
+                              const std::string &option,
+                              const std::string &value)
    {
       return FALSE;
    }
@@ -222,7 +175,9 @@ protected:
 };
 
 #ifdef _WIN32
-class UnityPluginWin32 : public UnityPlugin {
+class UnityPluginWin32
+   : public UnityPlugin
+{
 public:
    UnityPluginWin32();
    virtual ~UnityPluginWin32();
index 99f90284662eadbc86492950925c21e7e0933d08..c6d019e13eac946a335fa1b8a7a9866e861620c3 100644 (file)
@@ -16,8 +16,8 @@
  *
  *********************************************************/
 
-/**
- * @file unityPlugin.c
+/*
+ * unityPluginEntry.cpp --
  *
  *    Implements the unity plugin for the tools services. Registers for the Unity
  *    RPC's and sets the Unity capabilities.
@@ -35,31 +35,35 @@ extern "C" {
    #include "unity.h"
    #include "vmware/tools/plugin.h"
    #include "vmware/tools/utils.h"
-};
 
-extern "C" {
    TOOLS_MODULE_EXPORT ToolsPluginData *ToolsOnLoad(ToolsAppCtx *ctx);
 };
 
 using namespace vmware::tools;
 
-/**
- * Called by the service core when the host requests the capabilities supported
- * by the guest tools.
+
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * UnityPluginCapabilities --
+ *
+ *      Called by the service core when the host requests the capabilities
+ *      supported by the guest tools.
+ *
+ * Results:
+ *      A list of capabilities to be sent to the host.
  *
- * @param[in]  src      Unused.
- * @param[in]  ctx      The app context.
- * @param[in]  set      Whether capabilities are being set or unset (unused).
- * @param[in]  plugin   Plugin registration data.
+ * Side effects:
  *
- * @return A list of capabilities to be sent to the host.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 static GArray *
-UnityPluginCapabilities(gpointer src,
-                        ToolsAppCtx *ctx,
-                        gboolean set,
-                        ToolsPluginData *plugin)
+UnityPluginCapabilities(gpointer src,            // IGNORED
+                        ToolsAppCtx *ctx,        // IN: The app context.
+                        gboolean set,            // IN: true if setting, else unsetting
+                        ToolsPluginData *plugin) // IN: Plugin registration data.
 {
    ToolsPlugin *pluginInstance = reinterpret_cast<ToolsPlugin*>(plugin->_private);
    ASSERT(pluginInstance);
@@ -67,28 +71,31 @@ UnityPluginCapabilities(gpointer src,
    std::vector<ToolsAppCapability> capabilities = pluginInstance->GetCapabilities(set);
 
    g_debug("%s: got capability signal, setting = %d.\n", __FUNCTION__, set);
-   return VMTools_WrapArray(&capabilities[0], sizeof capabilities[0], capabilities.size());
+   return VMTools_WrapArray(&capabilities[0], sizeof capabilities[0],
+                            capabilities.size());
 }
 
 
-/**
- * Handles a reset signal; just logs debug information. This callback is
- * called when the service receives a "reset" message from the VMX, meaning
- * the VMX may be restarting the RPC channel (due, for example, to restoring
- * a snapshot, resuming a VM or a VMotion), and should be used to reset any
- * application state that depends on the VMX.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * UnityPluginReset --
+ *
+ *      Handles a reset signal.  Just logs debug information.
  *
- * @param[in]  src      Event source.
- * @param[in]  ctx      The app context.
- * @param[in]  plugin   Plugin registration data.
+ * Results:
+ *      TRUE on success, FALSE on failure.
  *
- * @return TRUE on success.
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 static gboolean
-UnityPluginReset(gpointer src,
-                 ToolsAppCtx *ctx,
-                 ToolsPluginData *plugin)
+UnityPluginReset(gpointer src,            // IN: Event source.
+                 ToolsAppCtx *ctx,        // IN: The app context.
+                 ToolsPluginData *plugin) // IN: Plugin registration data.
 {
    ASSERT(ctx != NULL);
    g_debug("%s: reset signal for app %s\n", __FUNCTION__, ctx->name);
@@ -100,21 +107,26 @@ UnityPluginReset(gpointer src,
 }
 
 
-
-/**
- * Handles a shutdown callback; just logs debug information. This is called
- * before the service is shut down, and should be used to clean up any resources
- * that were initialized by the application.
+/*
+ *-----------------------------------------------------------------------------
  *
- * @param[in]  src      The source object.
- * @param[in]  ctx      The app context.
- * @param[in]  plugin   Plugin registration data.
+ * UnityPluginShutdown --
+ *
+ *      Handles a shutdown callback; just logs debug information.
+ *
+ * Results:
+ *      None.
+ *
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 static void
-UnityPluginShutdown(gpointer src,
-                    ToolsAppCtx *ctx,
-                    ToolsPluginData *plugin)
+UnityPluginShutdown(gpointer src,            // IN: The source object.
+                    ToolsAppCtx *ctx,        // IN: The app context.
+                    ToolsPluginData *plugin) // Plugin registration data.
 {
    g_debug("%s: shutdown signal.\n", __FUNCTION__);
 
@@ -128,26 +140,28 @@ UnityPluginShutdown(gpointer src,
 }
 
 
-/**
- * Handles a "Set_Option" callback. Just logs debug information. This callback
- * is called when the VMX sends a "Set_Option" command to tools, to configure
- * different options whose values are kept outside of the virtual machine.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * UnityPluginSetOption --
+ *
+ *      Handles a "Set_Option" callback. Just logs debug information.
  *
- * @param[in]  src      Event source.
- * @param[in]  ctx      The app context.
- * @param[in]  plugin   Plugin registration data.
- * @param[in]  option   Option being set.
- * @param[in]  value    Option value.
+ * Results:
+ *      TRUE on success, FALSE on failure.
  *
- * @return TRUE on success.
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 static gboolean
-UnityPluginSetOption(gpointer src,
-                     ToolsAppCtx *ctx,
-                     const gchar *option,
-                     const gchar *value,
-                     ToolsPluginData *plugin)
+UnityPluginSetOption(gpointer src,            // IN: Event source.
+                     ToolsAppCtx *ctx,        // IN: The app context.
+                     const gchar *option,     // IN: Option to set.
+                     const gchar *value,      // IN: Option value.
+                     ToolsPluginData *plugin) // IN: Plugin registration data.
 {
    g_debug("%s: set '%s' to '%s'\n", __FUNCTION__, option, value);
    ToolsPlugin *pluginInstance = reinterpret_cast<ToolsPlugin*>(plugin->_private);
@@ -157,17 +171,24 @@ UnityPluginSetOption(gpointer src,
 }
 
 
-/**
- * Plugin entry point. Returns the registration data. This is called once when
- * the plugin is loaded into the service process.
+/*
+ *-----------------------------------------------------------------------------
+ *
+ * ToolsOnLoad` --
+ *
+ *      Plugin entry point.  Returns the registration data.
  *
- * @param[in]  ctx   The app context.
+ * Results:
+ *      Registration data.
  *
- * @return The registration data.
+ * Side effects:
+ *      XXX.
+ *
+ *-----------------------------------------------------------------------------
  */
 
 TOOLS_MODULE_EXPORT ToolsPluginData *
-ToolsOnLoad(ToolsAppCtx *ctx)
+ToolsOnLoad(ToolsAppCtx *ctx)           // IN: The app context.
 {
    static ToolsPluginData regData = {
       "unity",
@@ -217,4 +238,3 @@ ToolsOnLoad(ToolsAppCtx *ctx)
 
    return NULL;
 }
-