Move documentation from methods to functions

pysoundfile.py

@@ -303,27 +303,9 @@ class SoundFile(object):
 
     def __init__(self, file, mode='r', sample_rate=None, channels=None,
                  subtype=None, endian=None, format=None, closefd=True):
-        """Open a new SoundFile.
-
-        If a file is opened with mode 'r' (the default) or 'rw',
-        no sample_rate, channels or file format need to be given. If a
-        file is opened with mode 'w', you must provide a sample_rate,
-        a number of channels, and a file format. An exception is the
-        RAW data format, which requires these data points for reading
-        as well.
-
-        File formats consist of three case-insensitive strings:
-         - a "major format" which is by default obtained from the
-           extension of the file name (if known) and which can be
-           forced with the format argument (e.g. format='WAVEX').
-         - a "subtype", e.g. 'PCM_24'. Most major formats have a default
-           subtype which is used if no subtype is specified.
-         - an "endian-ness": 'FILE' (default), 'LITTLE', 'BIG' or 'CPU'.
-           In most cases this doesn't have to be specified.
-
-        The functions available_formats() and available_subtypes() can
-        be used to obtain a list of all avaliable major formats and
-        subtypes, respectively.
+        """Create new SoundFile object.
+
+        See the module-level function open() for arguments.
 
         """
         try:
@@ -626,21 +608,8 @@ def read(self, frames=-1, dtype='float64', always_2d=True,
         position by the same number of frames.
         Use frames=-1 to read until the end of the file.
 
-        A two-dimensional NumPy array is returned, where the channels
-        are stored along the first dimension, i.e. as columns.
-        A two-dimensional array is returned even if the sound file has
-        only one channel.  Use always_2d=False to return a
-        one-dimensional array in this case.
-
-        If out is specified, the data is written into the given NumPy
-        array. In this case, the arguments frames, dtype and always_2d
-        are silently ignored!
-
-        If there is less data left in the file than requested, the rest
-        of the frames are filled with fill_value. If fill_value=None, a
-        smaller array is returned.
-        If out is given, only a part of it is overwritten and a view
-        containing all valid frames is returned.
+        For further keyword arguments see the module-level function
+        read().
 
         """
         self._check_if_closed()
@@ -702,9 +671,27 @@ def write(self, data):
 
 def open(file, mode='r', sample_rate=None, channels=None,
          subtype=None, endian=None, format=None, closefd=True):
-    """Return a new SoundFile object.
-
-    Takes the same arguments as SoundFile.__init__().
+    """Open a sound file for reading and/or writing.
+
+    If a file is opened with mode 'r' (the default) or 'rw',
+    no sample_rate, channels or file format need to be given. If a
+    file is opened with mode 'w', you must provide a sample_rate,
+    a number of channels, and a file format. An exception is the
+    RAW data format, which requires these data points for reading
+    as well.
+
+    File formats consist of three case-insensitive strings:
+        - a "major format" which is by default obtained from the
+        extension of the file name (if known) and which can be
+        forced with the format argument (e.g. format='WAVEX').
+        - a "subtype", e.g. 'PCM_24'. Most major formats have a default
+        subtype which is used if no subtype is specified.
+        - an "endian-ness": 'FILE' (default), 'LITTLE', 'BIG' or 'CPU'.
+        In most cases this doesn't have to be specified.
+
+    The functions available_formats() and available_subtypes() can
+    be used to obtain a list of all avaliable major formats and
+    subtypes, respectively.
 
     """
     return SoundFile(file, mode, sample_rate, channels,
@@ -724,9 +711,24 @@ def read(file, frames=-1, start=None, stop=None,
     Both start and stop accept negative indices to specify positions
     relative to the end of the file.
 
-    The keyword arguments out, dtype, fill_value and always_2d are
-    forwarded to SoundFile.read().
-    All further arguments are forwarded to SoundFile.__init__().
+    A two-dimensional NumPy array is returned, where the channels are
+    stored along the first dimension, i.e. as columns.
+    A two-dimensional array is returned even if the sound file has only
+    one channel.
+    Use always_2d=False to return a one-dimensional array in this case.
+
+    If out is specified, the data is written into the given NumPy array.
+    In this case, the arguments frames, dtype and always_2d are silently
+    ignored!
+
+    If there is less data left in the file than requested, the rest of
+    the frames are filled with fill_value. If fill_value=None, a smaller
+    array is returned.
+    If out is given, only a part of it is overwritten and a view
+    containing all valid frames is returned.
+
+    The keyword arguments sample_rate, channels, format, subtype and
+    endian are only needed for 'RAW' files. See open() for details.
 
     """
     if frames >= 0 and stop is not None: