Critical Sections Documentation Update

[Robert Shearman]

Changelog:
Improve documentation for critical sections.

-------------- next part --------------
Index: wine/dlls/ntdll/critsection.c
===================================================================
RCS file: /home/wine/wine/dlls/ntdll/critsection.c,v
retrieving revision 1.26
diff -u -p -r1.26 critsection.c
--- wine/dlls/ntdll/critsection.c	17 Jun 2004 23:11:08 -0000	1.26
+++ wine/dlls/ntdll/critsection.c	5 Sep 2004 11:19:43 -0000
@@ -77,13 +77,18 @@ static inline HANDLE get_semaphore( RTL_
 /***********************************************************************
  *           RtlInitializeCriticalSection   (NTDLL.@)
  *
- * Initialise a new RTL_CRITICAL_SECTION.
+ * Initializes a new critical section.
  *
  * PARAMS
- *  crit [O] Critical section to initialise
+ *  crit [O] Critical section to initialize
  *
- * RETURN
+ * RETURNS
  *  STATUS_SUCCESS.
+ *
+ * SEE
+ *  RtlInitializeCriticalSectionAndSpinCount(), RtlDeleteCriticalSection(),
+ *  RtlEnterCriticalSection(), RtlLeaveCriticalSection(),
+ *  RtlTryEnterCriticalSection(), RtlSetCriticalSectionSpinCount()
  */
 NTSTATUS WINAPI RtlInitializeCriticalSection( RTL_CRITICAL_SECTION *crit )
 {
@@ -93,18 +98,22 @@ NTSTATUS WINAPI RtlInitializeCriticalSec
 /***********************************************************************
  *           RtlInitializeCriticalSectionAndSpinCount   (NTDLL.@)
  *
- * Initialise a new RTL_CRITICAL_SECTION with a given spin count.
+ * Initializes a new critical section with a given spin count.
  *
  * PARAMS
- *   crit      [O] Critical section to initialise
+ *   crit      [O] Critical section to initialize
  *   spincount [I] Spin count for crit
  * 
  * RETURNS
  *  STATUS_SUCCESS.
  *
  * NOTES
- * The InitializeCriticalSectionAndSpinCount() (KERNEL32) function is
- * available on NT4SP3 or later, and Win98 or later.
+ *  Available on NT4 SP3 or later.
+ *
+ * SEE
+ *  RtlInitializeCriticalSection(), RtlDeleteCriticalSection(),
+ *  RtlEnterCriticalSection(), RtlLeaveCriticalSection(),
+ *  RtlTryEnterCriticalSection(), RtlSetCriticalSectionSpinCount()
  */
 NTSTATUS WINAPI RtlInitializeCriticalSectionAndSpinCount( RTL_CRITICAL_SECTION *crit, ULONG spincount )
 {
@@ -139,7 +148,7 @@ NTSTATUS WINAPI RtlInitializeCriticalSec
  * Sets the spin count of a critical section.
  *
  * PARAMS
- *   crit      [O] Critical section
+ *   crit      [I/O] Critical section
  *   spincount [I] Spin count for crit
  *
  * RETURNS
@@ -147,6 +156,11 @@ NTSTATUS WINAPI RtlInitializeCriticalSec
  *
  * NOTES
  *  If the system is not SMP, spincount is ignored and set to 0.
+ *
+ * SEE
+ *  RtlInitializeCriticalSection(), RtlInitializeCriticalSectionAndSpinCount(),
+ *  RtlDeleteCriticalSection(), RtlEnterCriticalSection(),
+ *  RtlLeaveCriticalSection(), RtlTryEnterCriticalSection()
  */
 ULONG WINAPI RtlSetCriticalSectionSpinCount( RTL_CRITICAL_SECTION *crit, ULONG spincount )
 {
@@ -159,13 +173,18 @@ ULONG WINAPI RtlSetCriticalSectionSpinCo
 /***********************************************************************
  *           RtlDeleteCriticalSection   (NTDLL.@)
  *
- * Free the resources used by an RTL_CRITICAL_SECTION.
+ * Frees the resources used by an RTL_CRITICAL_SECTION.
  *
  * PARAMS
  *  crit [I/O] Critical section to free
  *
  * RETURNS
  *  STATUS_SUCCESS.
+ *
+ * SEE
+ *  RtlInitializeCriticalSection(), RtlInitializeCriticalSectionAndSpinCount(),
+ *  RtlDeleteCriticalSection(), RtlEnterCriticalSection(),
+ *  RtlLeaveCriticalSection(), RtlTryEnterCriticalSection()
  */
 NTSTATUS WINAPI RtlDeleteCriticalSection( RTL_CRITICAL_SECTION *crit )
 {
@@ -190,13 +209,22 @@ NTSTATUS WINAPI RtlDeleteCriticalSection
 /***********************************************************************
  *           RtlpWaitForCriticalSection   (NTDLL.@)
  *
- * Wait for an RTL_CRITICAL_SECTION to become free.
+ * Waits for a busy critical section to become free.
  * 
  * PARAMS
  *  crit [I/O] Critical section to wait for
  *
  * RETURNS
  *  STATUS_SUCCESS.
+ *
+ * NOTES
+ *  Use RtlEnterCriticalSection() instead of this function as it is often much
+ *  faster.
+ *
+ * SEE
+ *  RtlInitializeCriticalSection(), RtlInitializeCriticalSectionAndSpinCount(),
+ *  RtlDeleteCriticalSection(), RtlEnterCriticalSection(),
+ *  RtlLeaveCriticalSection(), RtlTryEnterCriticalSection()
  */
 NTSTATUS WINAPI RtlpWaitForCriticalSection( RTL_CRITICAL_SECTION *crit )
 {
@@ -244,6 +272,24 @@ NTSTATUS WINAPI RtlpWaitForCriticalSecti
 
 /***********************************************************************
  *           RtlpUnWaitCriticalSection   (NTDLL.@)
+ *
+ * Notifies other threads waiting on the busy critical section that it has
+ * become free.
+ * 
+ * PARAMS
+ *  crit [I/O] Critical section
+ *
+ * RETURNS
+ *  STATUS_SUCCESS.
+ *
+ * NOTES
+ *  Use RtlLeaveCriticalSection() instead of this function as it is often much
+ *  faster.
+ *
+ * SEE
+ *  RtlInitializeCriticalSection(), RtlInitializeCriticalSectionAndSpinCount(),
+ *  RtlDeleteCriticalSection(), RtlEnterCriticalSection(),
+ *  RtlLeaveCriticalSection(), RtlTryEnterCriticalSection()
  */
 NTSTATUS WINAPI RtlpUnWaitCriticalSection( RTL_CRITICAL_SECTION *crit )
 {
@@ -257,7 +303,7 @@ NTSTATUS WINAPI RtlpUnWaitCriticalSectio
 /***********************************************************************
  *           RtlEnterCriticalSection   (NTDLL.@)
  *
- * Enter an RTL_CRITICAL_SECTION.
+ * Enters a critical section, waiting for it to become available if necessary.
  *
  * PARAMS
  *  crit [I/O] Critical section to enter
@@ -265,8 +311,10 @@ NTSTATUS WINAPI RtlpUnWaitCriticalSectio
  * RETURNS
  *  STATUS_SUCCESS. The critical section is held by the caller.
  *  
- * NOTES
- *  The caller will wait until the critical section is availale.
+ * SEE
+ *  RtlInitializeCriticalSection(), RtlInitializeCriticalSectionAndSpinCount(),
+ *  RtlDeleteCriticalSection(), RtlSetCriticalSectionSpinCount(),
+ *  RtlLeaveCriticalSection(), RtlTryEnterCriticalSection()
  */
 NTSTATUS WINAPI RtlEnterCriticalSection( RTL_CRITICAL_SECTION *crit )
 {
@@ -307,7 +355,7 @@ done:
 /***********************************************************************
  *           RtlTryEnterCriticalSection   (NTDLL.@)
  *
- * Enter an RTL_CRITICAL_SECTION without waiting.
+ * Tries to enter a critical section without waiting.
  *
  * PARAMS
  *  crit [I/O] Critical section to enter
@@ -315,6 +363,11 @@ done:
  * RETURNS
  *  Success: TRUE. The critical section is held by the caller.
  *  Failure: FALSE. The critical section is currently held by another thread.
+ *
+ * SEE
+ *  RtlInitializeCriticalSection(), RtlInitializeCriticalSectionAndSpinCount(),
+ *  RtlDeleteCriticalSection(), RtlEnterCriticalSection(),
+ *  RtlLeaveCriticalSection(), RtlSetCriticalSectionSpinCount()
  */
 BOOL WINAPI RtlTryEnterCriticalSection( RTL_CRITICAL_SECTION *crit )
 {
@@ -338,13 +391,18 @@ BOOL WINAPI RtlTryEnterCriticalSection( 
 /***********************************************************************
  *           RtlLeaveCriticalSection   (NTDLL.@)
  *
- * Leave an RTL_CRITICAL_SECTION.
+ * Leaves a critical section.
  *
  * PARAMS
- *  crit [I/O] Critical section to enter
+ *  crit [I/O] Critical section to leave.
  *
  * RETURNS
  *  STATUS_SUCCESS.
+ *
+ * SEE
+ *  RtlInitializeCriticalSection(), RtlInitializeCriticalSectionAndSpinCount(),
+ *  RtlDeleteCriticalSection(), RtlEnterCriticalSection(),
+ *  RtlSetCriticalSectionSpinCount(), RtlTryEnterCriticalSection()
  */
 NTSTATUS WINAPI RtlLeaveCriticalSection( RTL_CRITICAL_SECTION *crit )
 {