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.

2 files changed, 35 insertions, 6 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}
diff --git a/PC/winsound.c b/PC/winsound.c
index b3b1bae..e182db5 100644
--- a/PC/winsound.c
+++ b/PC/winsound.c
@@ -59,7 +59,7 @@ static char sound_beep_doc[] =
 static char sound_module_doc[] =
 "PlaySound(sound, flags) - play a sound\n"
 "SND_FILENAME - sound is a wav file name\n"
-"SND_ALIAS - sound is a control panel sound association name\n"
+"SND_ALIAS - sound is a registry sound association name\n"
 "SND_LOOP - Play the sound repeatedly; must also specify SND_ASYNC\n"
 "SND_MEMORY - sound is a memory image of a wav file\n"
 "SND_PURGE - stop all instances of the specified sound\n"