DOC: clean up class and some function docstrings

Looking at the built docs pointed out that some classes in particular
did not have good first line of docstrings.  Go back over docstrings
adding first lines to some, minor expansion for others.

Author: matthew-brett

nibabel/analyze.py

@@ -894,6 +894,8 @@ def _chk_pixdims(hdr, fix=False):
 
 
 class AnalyzeImage(SpatialImage):
+    """ Class for basic Analyze format image
+    """
     header_class = AnalyzeHeader
     files_types = (('image','.img'), ('header','.hdr'))
     _compressed_exts = ('.gz', '.bz2')

nibabel/freesurfer/mghformat.py

@@ -6,7 +6,7 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-''' Header reading / writing functions for mgh image format
+''' Header and image reading / writing functions for MGH image format
 
 Author: Krish Subramaniam
 '''
@@ -71,7 +71,8 @@ class MGHError(Exception):
 
 
 class MGHHeader(object):
-    '''
+    ''' Class for MGH format header
+
     The header also consists of the footer data which MGH places after the data
     chunk.
     '''
@@ -454,6 +455,8 @@ def writeftr_to(self, fileobj):
 
 
 class MGHImage(SpatialImage):
+    """ Class for MGH format image
+    """
     header_class = MGHHeader
     files_types = (('image', '.mgh'),)
     _compressed_exts = (('.gz',))

nibabel/minc1.py

@@ -37,11 +37,11 @@
 
 
 class MincError(Exception):
-    pass
+    """ Error when reading MINC files """
 
 
 class Minc1File(object):
-    ''' Class to wrap MINC 1 format opened netcdf object
+    ''' Class to wrap MINC1 format opened netcdf object
 
     Although it has some of the same methods as a ``Header``, we use
     this only when reading a MINC file, to pull out useful header
@@ -239,7 +239,7 @@ def get_scaled_data(self, sliceobj=()):
 
 
 class MincImageArrayProxy(object):
-    ''' Minc implementation of array proxy protocol
+    ''' MINC implementation of array proxy protocol
 
     The array proxy allows us to freeze the passed fileobj and
     header such that it returns the expected data array.
@@ -266,6 +266,8 @@ def __getitem__(self, sliceobj):
 
 
 class MincHeader(Header):
+    """ Class to contain header for MINC formats
+    """
     # We don't use the data layout - this just in case we do later
     data_layout = 'C'
 
@@ -279,7 +281,7 @@ def data_from_fileobj(self, fileobj):
 
 
 class Minc1Image(SpatialImage):
-    ''' Class for MINC 1 format images
+    ''' Class for MINC1 format images
 
     The MINC1 image class uses the default header type, rather than a specific
     MINC header type - and reads the relevant information from the MINC file on
@@ -310,6 +312,10 @@ def from_file_map(klass, file_map):
 
 # Backwards compatibility
 class MincFile(FutureWarningMixin, Minc1File):
+    """ Deprecated alternative name for Minc1File
+    """
     warn_message = 'MincFile is deprecated; please use Minc1File instead'
 class MincImage(FutureWarningMixin, Minc1Image):
+    """ Deprecated alternative name for Minc1Image
+    """
     warn_message = 'MincImage is deprecated; please use Minc1Image instead'

nibabel/nifti1.py

@@ -7,6 +7,8 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 ''' Read / write access to NIfTI1 image format
+
+NIfTI1 format defined at http://nifti.nimh.nih.gov/nifti-1/
 '''
 from __future__ import division, print_function
 import warnings
@@ -518,10 +520,10 @@ def from_fileobj(klass, fileobj, size, byteswap):
 
 
 class Nifti1Header(SpmAnalyzeHeader):
-    ''' Class for NIFTI1 header
+    ''' Class for NIfTI1 header
 
-    The NIFTI1 header has many more coded fields than the simpler Analyze
-    variants.  Nifti1 headers also have extensions.
+    The NIfTI1 header has many more coded fields than the simpler Analyze
+    variants.  NIfTI1 headers also have extensions.
 
     Nifti allows the header to be a separate file, as part of a nifti image /
     header pair, or to precede the data in a single file.  The object needs to
@@ -1067,7 +1069,7 @@ def set_slope_inter(self, slope, inter=None):
         self._structarr['scl_inter'] = inter
 
     def get_dim_info(self):
-        ''' Gets nifti MRI slice etc dimension information
+        ''' Gets NIfTI MRI slice etc dimension information
 
         Returns
         -------
@@ -1080,7 +1082,7 @@ def get_dim_info(self):
 
         where ``data array`` is the array returned by ``get_data``
 
-        Because nifti1 files are natively Fortran indexed:
+        Because NIfTI1 files are natively Fortran indexed:
           0 is fastest changing in file
           1 is medium changing in file
           2 is slowest changing in file
@@ -1262,7 +1264,7 @@ def get_slice_duration(self):
 
         Notes
         -----
-        The Nifti1 spec appears to require the slice dimension to be
+        The NIfTI1 spec appears to require the slice dimension to be
         defined for slice_duration to have meaning.
         '''
         _, _, slice_dim = self.get_dim_info()
@@ -1572,12 +1574,14 @@ def _chk_xform_code(klass, code_type, hdr, fix):
 
 
 class Nifti1PairHeader(Nifti1Header):
-    ''' Class for nifti1 pair header '''
+    ''' Class for NIfTI1 pair header '''
     # Signal whether this is single (header + data) file
     is_single = False
 
 
 class Nifti1Pair(analyze.AnalyzeImage):
+    """ Class for NIfTI1 format image, header pair
+    """
     header_class = Nifti1PairHeader
 
     def __init__(self, dataobj, affine, header=None,
@@ -1795,6 +1799,8 @@ def set_sform(self, affine, code=None, **kwargs):
 
 
 class Nifti1Image(Nifti1Pair):
+    """ Class for single file NIfTI1 format image
+    """
     header_class = Nifti1Header
     files_types = (('image', '.nii'),)
 
@@ -1815,7 +1821,7 @@ def update_header(self):
 
 
 def load(filename):
-    """ Load nifti1 single or pair from `filename`
+    """ Load NIfTI1 single or pair from `filename`
 
     Parameters
     ----------
@@ -1825,11 +1831,11 @@ def load(filename):
     Returns
     -------
     img : Nifti1Image or Nifti1Pair
-        nifti1 single or pair image instance
+        NIfTI1 single or pair image instance
 
     Raises
     ------
-    ImageFileError: if `filename` doesn't look like nifti1
+    ImageFileError: if `filename` doesn't look like NIfTI1
     IOError : if `filename` does not exist
     """
     try:
@@ -1840,7 +1846,7 @@ def load(filename):
 
 
 def save(img, filename):
-    """ Save nifti1 single or pair to `filename`
+    """ Save NIfTI1 single or pair to `filename`
 
     Parameters
     ----------

nibabel/nifti2.py

@@ -15,7 +15,6 @@
 Stuff about the CIFTI file format here:
 
     http://www.nitrc.org/plugins/mwiki/index.php/cifti:ConnectivityMatrixFileFormats
-
 '''
 
 import numpy as np
@@ -125,7 +124,12 @@
 
 
 class Nifti2Header(Nifti1Header):
-    ''' Class for Nifti2 single file header '''
+    """ Class for NIfTI2 header
+
+    NIfTI2 is a slightly simplified variant of NIfTI1 which replaces 32-bit
+    floats with 64-bit floats, and increases some integer widths to 32 or 64
+    bits.
+    """
     template_dtype = header_dtype
     pair_vox_offset = 0
     single_vox_offset = 544
@@ -219,21 +223,25 @@ def _chk_eol_check(hdr, fix=False):
 
 
 class Nifti2PairHeader(Nifti2Header):
-    ''' Class for nifti2 pair header '''
+    ''' Class for NIfTI2 pair header '''
     # Signal whether this is single (header + data) file
     is_single = False
 
 
 class Nifti2Pair(Nifti1Pair):
+    """ Class for NIfTI2 format image, header pair
+    """
     header_class = Nifti2PairHeader
 
 
 class Nifti2Image(Nifti1Image):
+    """ Class for single file NIfTI2 format image
+    """
     header_class = Nifti2Header
 
 
 def load(filename):
-    """ Load nifti2 single or pair from `filename`
+    """ Load NIfTI2 single or pair image from `filename`
 
     Parameters
     ----------
@@ -258,7 +266,7 @@ def load(filename):
 
 
 def save(img, filename):
-    """ Save nifti2 single or pair to `filename`
+    """ Save NIfTI2 single or pair to `filename`
 
     Parameters
     ----------

nibabel/spm2analyze.py

@@ -25,8 +25,14 @@
 
 
 class Spm2AnalyzeHeader(spm99.Spm99AnalyzeHeader):
-    ''' SPM2 header; adds possibility of reading, but not writing DC
-    offset for data'''
+    ''' Class for SPM2 variant of basic Analyze header
+
+    SPM2 variant adds the following to basic Analyze format:
+
+    * voxel origin;
+    * slope scaling of data;
+    * reading - but not writing - intercept of data.
+    '''
 
     # Copies of module level definitions
     template_dtype = header_dtype
@@ -110,6 +116,8 @@ def get_slope_inter(self):
 
 
 class Spm2AnalyzeImage(spm99.Spm99AnalyzeImage):
+    """ Class for SPM2 variant of basic Analyze image
+    """
     header_class = Spm2AnalyzeHeader
 
 

nibabel/spm99analyze.py

@@ -97,7 +97,14 @@ def set_slope_inter(self, slope, inter=None):
 
 
 class Spm99AnalyzeHeader(SpmAnalyzeHeader):
-    ''' Adds origin functionality to base SPM header '''
+    ''' Class for SPM99 variant of basic Analyze header
+
+    SPM99 variant adds the following to basic Analyze format:
+
+    * voxel origin;
+    * slope scaling of data.
+    '''
+
     def get_origin_affine(self):
         ''' Get affine from header, using SPM origin field if sensible
 
@@ -224,6 +231,8 @@ def _chk_origin(hdr, fix=False):
 
 
 class Spm99AnalyzeImage(analyze.AnalyzeImage):
+    """ Class for SPM99 variant of basic Analyze image
+    """
     header_class = Spm99AnalyzeHeader
     files_types = (('image', '.img'),
                    ('header', '.hdr'),

nibabel/trackvis.py

@@ -86,11 +86,13 @@
 
 
 class HeaderError(Exception):
-    pass
+    """ Error in trackvis header
+    """
 
 
 class DataError(Exception):
-    pass
+    """ Error in trackvis data
+    """
 
 
 def read(fileobj, as_generator=False, points_space=None):
@@ -741,7 +743,8 @@ def aff_to_hdr(affine, trk_hdr, pos_vox=None, set_order=None):
 
 
 class TrackvisFileError(Exception):
-    pass
+    """ Error from TrackvisFile class
+    """
 
 
 class TrackvisFile(object):