Fixups for #431 following review

package/MDAnalysis/coordinates/base.py

@@ -1617,7 +1617,6 @@ def __init__(cls, name, bases, classdict):
             except KeyError:
                 pass
             else:
-                # All multiframe writers work as a singleframe?
                 for f in fmt:
                     _SINGLEFRAME_WRITERS[f] = cls
                 try:

package/MDAnalysis/coordinates/core.py

@@ -53,8 +53,14 @@ def get_reader_for(filename, permissive=False, format=None):
     kwargs
         Keyword arguments for the selected Reader class.
 
-    Automatic detection is disabled when an explicit *format* is
-    provided.
+    Returns
+    -------
+    A Reader object
+
+    Notes
+    -----
+        Automatic detection is disabled when an explicit *format* is
+        provided.
     """
     if format is None:
         format = util.guess_format(filename)
@@ -90,14 +96,18 @@ def reader(filename, **kwargs):
 
     Parameters
     ----------
-    filename : str
-        filename of the input trajectory or coordinate file
+    filename : str or tuple
+        filename (or tuple of filenames) of the input coordinate file
     permissive : bool
         If set to ``True``, a reader is selected that is more tolerant of the
         input (currently only implemented for PDB). [``False``]
     kwargs
         Keyword arguments for the selected Reader class.
 
+    Returns
+    -------
+    A Reader object
+
     .. SeeAlso:: For trajectory formats: :class:`~DCD.DCDReader`,
        :class:`~XTC.XTCReader`, :class:`~TRR.TRRReader`,
        :class:`~XYZ.XYZReader`.  For single frame formats:
@@ -136,6 +146,10 @@ def get_writer_for(filename=None, format='DCD', multiframe=None):
         write a single coordinate frame; ``None``: first try trajectory (multi
         frame writers), then the single frame ones. Default is ``None``.
 
+    Returns
+    -------
+    A Writer object
+
     .. versionchanged:: 0.7.6
        Added *multiframe* keyword; the default ``None`` reflects the previous
        behaviour.
@@ -199,6 +213,10 @@ def writer(filename, n_atoms=None, **kwargs):
        Some readers accept additional arguments, which need to be looked
        up in the documentation of the reader.
 
+    Returns
+    -------
+    A Writer object
+
     .. SeeAlso:: :class:`~MDAnalysis.coordinates.DCD.DCDWriter` for DCD
                  trajectories or :class:`~MDAnalysis.coordinates.XTC.XTCWriter`
                  and :class:`~MDAnalysis.coordinates.TRR.TRRWriter` for Gromacs.