vcl: document the non-obvious WinSalInstance's WaitMutex members

Change-Id: I004f082c9e4a17aeb7a8bd778bf45dff93e47ee8

1 files changed, 15 insertions, 5 deletions

diff --git a/vcl/inc/win/salinst.h b/vcl/inc/win/salinst.h
index b3337aca9f85..6eab9b3227ef 100644
--- a/vcl/inc/win/salinst.h
+++ b/vcl/inc/win/salinst.h
@@ -27,11 +27,21 @@ class SalYieldMutex;
 class WinSalInstance : public SalInstance
 {
 public:
-    HINSTANCE           mhInst;                 // Instance Handle
-    HWND                mhComWnd;               // window, for communication (between threads and the main thread)
-    SalYieldMutex*      mpSalYieldMutex;        // Sal-Yield-Mutex
-    osl::Mutex*         mpSalWaitMutex;         // Sal-Wait-Mutex
-    sal_uInt16              mnYieldWaitCount;       // Wait-Count
+    /// Instance Handle
+    HINSTANCE           mhInst;
+    /// invisible Window so non-main threads can SendMessage() the main thread
+    HWND                mhComWnd;
+    /// The Yield mutex ensures that only one thread calls into VCL
+    SalYieldMutex*      mpSalYieldMutex;
+    /// The Wait mutex ensures increment of mnYieldWaitCount and acquisition
+    /// or release of mpSalYieldMutex is atomic
+    osl::Mutex*         mpSalWaitMutex;
+    /// count main thread's pending ImplSalYieldMutexAcquireWithWait() calls
+    /// (it's not clear to me if this will be > 1 in practice; it would be
+    /// possible if main thread's handling of SAL_MSG_* sent by other threads
+    /// via SendMessage() ends up calling ImplSalYieldMutexAcquireWithWait())
+    sal_uInt16          mnYieldWaitCount;
+
 public:
     WinSalInstance();
     virtual ~WinSalInstance();