Rewrite the description of setparameters() so it actually reflects the

gward · gward · commit fb1b5a164dc1 · 2003-05-29T01:39:32.000Z
code (which has also been recently overhauled, so that it can be
documented without embarassment).

'error' has been renamed to 'OSSAudioError'.

Minor wordsmithing.
diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex
@@ -49,14 +49,17 @@ \section{\module{ossaudiodev} ---
 
 \module{ossaudiodev} defines the following variables and functions:
 
-\begin{excdesc}{error}
+\begin{excdesc}{OSSAudioError}
 This exception is raised on certain errors.  The argument is a string
 describing what went wrong.
 
 (If \module{ossaudiodev} receives an error from a system call such as
 \cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, it
 raises \exception{IOError}.  Errors detected directly by
-\module{ossaudiodev} result in \exception{ossaudiodev.error}.)
+\module{ossaudiodev} result in \exception{OSSAudioError}.)
+
+(For backwards compatibility, the exception class is also available as
+\code{ossaudiodev.error}.)
 \end{excdesc}
 
 \begin{funcdesc}{open}{\optional{device, }mode}
@@ -201,8 +204,8 @@ \subsection{Audio Device Objects \label{ossaudio-device-objects}}
 \constant{AFMT_QUERY}.  
 \end{methoddesc}
 
-\begin{methoddesc}[audio device]{channels}{num_channels}
-Set the number of output channels to \var{num_channels}.  A value of 1
+\begin{methoddesc}[audio device]{channels}{nchannels}
+Set the number of output channels to \var{nchannels}.  A value of 1
 indicates monophonic sound, 2 stereophonic.  Some devices may have more
 than 2 channels, and some high-end devices may not support mono.
 Returns the number of channels the device was set to.
@@ -241,16 +244,33 @@ \subsection{Audio Device Objects \label{ossaudio-device-objects}}
 user input, or before doing disk I/O.
 \end{methoddesc}
 
-Convenience methods
+The following convenience methods combine several ioctls, or one ioctl
+and some simple calculations.
+
+\begin{methoddesc}[audio device]{setparameters}
+  {format, nchannels, samplerate \optional{, strict=False}}
 
-\begin{methoddesc}[audio device]{setparameters}{samplerate,num_channels,format,emulate}
-Initialise the sound device in one method.  \var{samplerate},
-\var{channels} and \var{format} should be as specified in the
-\method{speed()}, \method{channels()} and \method{setfmt()}
-methods.  If \var{emulate} is true, attempt to find the closest matching
-format instead, otherwise raise ValueError if the device does not
-support the format.  The default is to raise ValueError on unsupported
-formats.
+Set the key audio sampling parameters---sample format, number of
+channels, and sampling rate---in one method call.  \var{format}, 
+\var{nchannels}, and \var{samplerate} should be as specified in the
+\method{setfmt()}, \method{channels()}, and \method{speed()} 
+methods.  If \var{strict} is true, \method{setparameters()} checks to
+see if each parameter was actually set to the requested value, and
+raises \exception{OSSAudioError} if not.  Returns a tuple (\var{format},
+\var{nchannels}, \var{samplerate}) indicating the parameter values that
+were actually set by the device driver (i.e., the same as the return
+valus of \method{setfmt()}, \method{channels()}, and \method{speed()}).
+
+For example,
+\begin{verbatim}
+  (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
+\end{verbatim}
+is equivalent to
+\begin{verbatim}
+  fmt = dsp.setfmt(fmt)
+  channels = dsp.channels(channels)
+  rate = dsp.rate(channels)
+\end{verbatim}
 \end{methoddesc}
 
 \begin{methoddesc}[audio device]{bufsize}{}
