DOC: Cleanup read/write docstrings

Add tables clarifying that 8-bit is unsigned, giving max and min values

scipy/io/wavfile.py

@@ -151,37 +151,55 @@ def _read_riff_chunk(fid):
 
     return fsize, is_big_endian
 
-# open a wave-file
-
 
 def read(filename, mmap=False):
     """
+    Open a WAV file
+
     Return the sample rate (in samples/sec) and data from a WAV file.
 
     Parameters
     ----------
     filename : string or open file handle
         Input wav file.
     mmap : bool, optional
-        Whether to read data as memory mapped.
+        Whether to read data as memory-mapped.
         Only to be used on real files (Default: False).
 
         .. versionadded:: 0.12.0
 
     Returns
     -------
     rate : int
-        Sample rate of wav file.
+        Sample rate of wav file as a Python integer.
     data : numpy array
-        Data read from wav file.
+        Data read from wav file.  Data-type is determined from the file;
+        see Notes.
 
     Notes
     -----
-    * The file can be an open file or a filename.
-    * The returned sample rate is a Python integer.
-    * The data is returned as a numpy array with a data-type determined
-      from the file.
-    * This function cannot read wav files with 24 bit data.
+    This function cannot read wav files with 24-bit data.
+
+    Common data types: [1]_
+
+    =====================  ===========  ===========  =============
+         WAV format            Min          Max       NumPy dtype
+    =====================  ===========  ===========  =============
+    32-bit floating-point  -1.0         +1.0         float32
+    32-bit PCM             -2147483648  +2147483647  int32
+    16-bit PCM             -32768       +32767       int16
+    8-bit PCM              0            255          uint8
+    =====================  ===========  ===========  =============
+
+    Note that 8-bit PCM is unsigned.
+
+    References
+    ----------
+
+    .. [1] IBM Corporation and Microsoft Corporation, "Multimedia Programming
+       Interface and Data Specifications 1.0", section "Data Format of the
+       Samples", August 1991
+       http://www-mmsp.ece.mcgill.ca/documents/audioformats/wave/Docs/riffmci.pdf
 
     """
     if hasattr(filename, 'read'):
@@ -231,9 +249,6 @@ def read(filename, mmap=False):
 
     return rate, data
 
-# Write a wave-file
-# sample rate, data
-
 
 def write(filename, rate, data):
     """
@@ -250,12 +265,31 @@ def write(filename, rate, data):
 
     Notes
     -----
-    * The file can be an open file or a filename.
-
     * Writes a simple uncompressed WAV file.
-    * The bits-per-sample will be determined by the data-type.
     * To write multiple-channels, use a 2-D array of shape
       (Nsamples, Nchannels).
+    * The bits-per-sample and PCM/float will be determined by the data-type.
+
+    Common data types: [1]_
+
+    =====================  ===========  ===========  =============
+         WAV format            Min          Max       NumPy dtype
+    =====================  ===========  ===========  =============
+    32-bit floating-point  -1.0         +1.0         float32
+    32-bit PCM             -2147483648  +2147483647  int32
+    16-bit PCM             -32768       +32767       int16
+    8-bit PCM              0            255          uint8
+    =====================  ===========  ===========  =============
+
+    Note that 8-bit PCM is unsigned.
+
+    References
+    ----------
+
+    .. [1] IBM Corporation and Microsoft Corporation, "Multimedia Programming
+       Interface and Data Specifications 1.0", section "Data Format of the
+       Samples", August 1991
+       http://www-mmsp.ece.mcgill.ca/documents/audioformats/wave/Docs/riffmci.pdf
 
     """
     if hasattr(filename, 'write'):