Flesh out PlaySound() docs enough so that SND_ALIAS isn't hopelessly confusing.

If someone knows how to turn the new table of guaranteed-registered system
sounds into a LaTeX table, be my guest.

1 files changed, 34 insertions, 5 deletions

diff --git a/Doc/lib/libwinsound.tex b/Doc/lib/libwinsound.tex
index 53b7256..a873b9e 100644
--- a/Doc/lib/libwinsound.tex
+++ b/Doc/lib/libwinsound.tex
@@ -40,21 +40,49 @@ two functions and several constants.
 
 \begin{datadesc}{SND_FILENAME}
   The \var{sound} parameter is the name of a WAV file.
+  Do not use with \constant{SND_ALIAS}.
 \end{datadesc}
 
 \begin{datadesc}{SND_ALIAS}
-  The \var{sound} parameter should be interpreted as a control panel
-  sound association name.
+  The \var{sound} parameter is a sound association name from the registry.
+  If the registry contains no such name, play the system default sound
+  unless \constant{SND_NODEFAULT} is also specified.
+  If no default sound is registered, raise RuntimeError.
+  Do not use with \constant{SND_FILENAME).
+
+  All Win32 systems support at least the following; most systems support
+  many more:
+
+  \begin{verbatim}
+  PlaySound argument    Corresponding Control Panel -> Sounds name
+  ------------------    ------------------------------------------
+  'SystemAsterisk'      Asterisk
+  'SystemExclamation'   Exclamation
+  'SystemExit'          Exit Windows
+  'SystemHand'          Critical Stop
+  'SystemQuestion'      Question
+  \end{verbatim}
+
+  For example,
+
+  \begin{verbatim}
+    # Play Windows exit sound.
+    winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
+
+    # Probably play Windows default sound, if any is registered (because
+    # "*" probably isn't the registered name of any sound).
+    winsound.PlaySound("*", winsound.SND_ALIAS)
+  \end{verbatim}
 \end{datadesc}
 
 \begin{datadesc}{SND_LOOP}
   Play the sound repeatedly.  The \constant{SND_ASYNC} flag must also
-  be used to avoid blocking.
+  be used to avoid blocking.  Cannot be used with \constant{SND_MEMORY}.
 \end{datadesc}
 
 \begin{datadesc}{SND_MEMORY}
   The \var{sound} parameter to \function{PlaySound()} is a memory
-  image of a WAV file.
+  image of a WAV file, as a string.
 
   \strong{Note:}  This module does not support playing from a memory
   image asynchronously, so a combination of this flag and
@@ -70,7 +98,8 @@ two functions and several constants.
 \end{datadesc}
 
 \begin{datadesc}{SND_NODEFAULT}
-  If the specified sound cannot be found, do not play a default beep.
+  If the specified sound cannot be found, do not play the system default
+  sound.
 \end{datadesc}
 
 \begin{datadesc}{SND_NOSTOP}