Index: /trunk/src/VBox/Additions/common/VBoxGuest/VBoxGuest.cpp
===================================================================
--- /trunk/src/VBox/Additions/common/VBoxGuest/VBoxGuest.cpp	(revision 50390)
+++ /trunk/src/VBox/Additions/common/VBoxGuest/VBoxGuest.cpp	(revision 50391)
@@ -75,4 +75,7 @@
 #define VBOXGUEST_ACQUIRE_STYLE_EVENTS (VMMDEV_EVENT_DISPLAY_CHANGE_REQUEST | VMMDEV_EVENT_SEAMLESS_MODE_CHANGE_REQUEST)
 
+/** Return the mask of VMM device events that this session is allowed to see,
+ *  ergo, all events except those in "acquire" mode which have not been acquired
+ *  by this session. */
 DECLINLINE(uint32_t) VBoxGuestCommonGetHandledEventsLocked(PVBOXGUESTDEVEXT pDevExt, PVBOXGUESTSESSION pSession)
 {
@@ -80,4 +83,6 @@
         return VMMDEV_EVENT_VALID_EVENT_MASK;
 
+    /** @note VMMDEV_EVENT_VALID_EVENT_MASK should actually be the mask of valid
+     *        capabilities, but that doesn't affect this code. */
     uint32_t u32AllowedGuestCaps = pSession->u32AquiredGuestCaps | (VMMDEV_EVENT_VALID_EVENT_MASK & ~pDevExt->u32AcquireModeGuestCaps);
     uint32_t u32CleanupEvents = VBOXGUEST_ACQUIRE_STYLE_EVENTS;
@@ -98,4 +103,7 @@
 }
 
+/** Puts a capability in "acquire" or "set" mode and returns the mask of
+ * capabilities currently in the other mode.  Once a capability has been put in
+ * one of the two modes it can no longer be removed from that mode. */
 DECLINLINE(bool) VBoxGuestCommonGuestCapsModeSet(PVBOXGUESTDEVEXT pDevExt, uint32_t fCaps, bool fAcquire, uint32_t *pu32OtherVal)
 {
@@ -2537,4 +2545,16 @@
 }
 
+/** Check whether any unreported VMM device events should be reported to any of
+ * the currently listening sessions.  In addition, report any events in
+ * @a fGenFakeEvents.
+ * @note This is called by GUEST_CAPS_ACQUIRE in case any pending events can now
+ *       be dispatched to the session which acquired capabilities.  The fake
+ *       events are a hack to wake up threads in that session which would not
+ *       otherwise be woken.
+ * @todo Why not just use CANCEL_ALL_WAITEVENTS to do the waking up rather than
+ *       adding additional code to the driver?
+ * @todo Why does acquiring capabilities block and unblock events?  Capabilities
+ *       are supposed to control what is reported to the host, we already have
+ *       separate requests for blocking and unblocking events. */
 static void VBoxGuestCommonCheckEvents(PVBOXGUESTDEVEXT pDevExt, PVBOXGUESTSESSION pSession, uint32_t fGenFakeEvents)
 {
@@ -2574,4 +2594,8 @@
 }
 
+/** Switch the capabilities in @a fOrMask to "acquire" mode if they are not
+ * already in "set" mode.  If @a enmFlags is not set to
+ * VBOXGUESTCAPSACQUIRE_FLAGS_CONFIG_ACQUIRE_MODE, also try to acquire those
+ * capabilities for the current session and release those in @a fNotFlag. */
 static int VBoxGuestCommonGuestCapsAcquire(PVBOXGUESTDEVEXT pDevExt, PVBOXGUESTSESSION pSession, uint32_t fOrMask, uint32_t fNotMask, VBOXGUESTCAPSACQUIRE_FLAGS enmFlags)
 {
Index: /trunk/src/VBox/Additions/common/VBoxGuest/VBoxGuestInternal.h
===================================================================
--- /trunk/src/VBox/Additions/common/VBoxGuest/VBoxGuestInternal.h	(revision 50390)
+++ /trunk/src/VBox/Additions/common/VBoxGuest/VBoxGuestInternal.h	(revision 50391)
@@ -180,9 +180,13 @@
     /** Callback and user data for a kernel mouse handler. */
     VBoxGuestMouseSetNotifyCallback MouseNotifyCallback;
-    /* list of caps used in acquire mode */
+    /** Guest capabilities which have been set to "acquire" mode.  This means
+     * that only one session can use them at a time, and that they will be
+     * automatically cleaned up if that session exits without doing so. */
     uint32_t                    u32AcquireModeGuestCaps;
-    /* list of caps used in set mode */
+    /** Guest capabilities which have been set to "set" mode.  This just means
+     * that they have been blocked from ever being set to "acquire" mode. */
     uint32_t                    u32SetModeGuestCaps;
-    /* currently acquired (and reported) guest caps */
+    /** Mask of all capabilities which are currently acquired by some session
+     * and as such reported to the host. */
     uint32_t                    u32GuestCaps;
 } VBOXGUESTDEVEXT;
@@ -235,5 +239,6 @@
     bool                        fOpened;
 #endif
-    /* Guest Caps Acquired & Reported by this session */
+    /** Mask of guest capabilities acquired by this session.  These will all be
+     *  reported to the host. */
     uint32_t                    u32AquiredGuestCaps;
     /** Whether a CANCEL_ALL_WAITEVENTS is pending.  This happens when