Improve documentation of properties

doc/conf.py

@@ -286,3 +286,6 @@ numpydoc_show_class_members = False
 
 # Include todos
 todo_include_todos = True
+
+# Keep the order of members as in the source code
+autodoc_member_order = 'bysource'

madarrays/mad_array.py

@@ -137,11 +137,11 @@ class MadArray(np.ndarray):
     implemented:
 
     * a :class:`MadArray` object with shape corresponding to the indices is
-    returned, with both the data matrix and the mask properly indexed. This
-    is the default mode;
+      returned, with both the data matrix and the mask properly indexed. This
+      is the default mode;
     * a :class:`MadArray` object with unchanged shape is returned,
-    where non-indexed entries are set as masked. This mode is selected by
-    setting the parameter :paramref:`masked_indexing` to True.
+      where non-indexed entries are set as masked. This mode is selected by
+      setting the parameter :paramref:`masked_indexing` to True.
 
     .. _numpy_behaviour_madarray:
 
@@ -388,14 +388,11 @@ class MadArray(np.ndarray):
 
     @property
     def known_mask(self):
-        """Boolean mask for known coefficients.
+        """Boolean mask for known coefficients (boolean nd-array).
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if the corresponding value
-            in the object is known. If complex masking, entries set to True if
-            both magnitude and phase are known.
+        Boolean array with entries set to True if the corresponding value
+        in the object is known. If complex masking, entries set to True if
+        both magnitude and phase are known.
         """
         if self._complex_masking:
             return self._mask == 0
@@ -404,14 +401,11 @@ class MadArray(np.ndarray):
 
     @property
     def unknown_mask(self):
-        """Boolean mask for unknown coefficients.
+        """Boolean mask for unknown coefficients (boolean nd-array).
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with values set to True if the corresponding value in
-            the object is unknown. If complex masking, entries set to True if
-            magnitude and/or phase are unknown.
+        Boolean array with values set to True if the corresponding value in
+        the object is unknown. If complex masking, entries set to True if
+        magnitude and/or phase are unknown.
         """
         if self._complex_masking:
             return self.any_unknown_mask
@@ -420,15 +414,13 @@ class MadArray(np.ndarray):
 
     @property
     def any_unknown_mask(self):
-        """Boolean mask for coefficients with unknown magnitude and/or phase.
+        """Boolean mask for coefficients with unknown magnitude and/or phase
+        (boolean nd-array).
 
         Not defined if non complex masking.
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if magnitude and/or phase
-            are unknown.
+        Boolean array with entries set to True if magnitude and/or phase
+        are unknown.
 
         Raises
         ------
@@ -440,15 +432,13 @@ class MadArray(np.ndarray):
 
     @property
     def all_unknown_mask(self):
-        """Boolean mask for coefficients with both unknown magnitude and phase.
+        """Boolean mask for coefficients with both unknown magnitude and phase
+        (boolean nd-array).
 
         Not defined if non complex masking.
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if both magnitude and phase
-            are unknown.
+        Boolean array with entries set to True if both magnitude and phase
+        are unknown.
 
         Raises
         ------
@@ -460,14 +450,11 @@ class MadArray(np.ndarray):
 
     @property
     def known_phase_mask(self):
-        """Boolean mask for coefficients with known phase.
+        """Boolean mask for coefficients with known phase (boolean nd-array).
 
         Not defined for int or float entries.
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if phase is known.
+        Boolean array with entries set to True if phase is known.
 
         Raises
         ------
@@ -479,14 +466,11 @@ class MadArray(np.ndarray):
 
     @property
     def unknown_phase_mask(self):
-        """Boolean mask for coefficients with unknown phase.
+        """Boolean mask for coefficients with unknown phase (boolean nd-array).
 
         Not defined for int or float entries.
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if phase is unknown
+        Boolean array with entries set to True if phase is unknown.
 
         Raises
         ------
@@ -498,14 +482,12 @@ class MadArray(np.ndarray):
 
     @property
     def known_magnitude_mask(self):
-        """Boolean mask for coefficients with known magnitude.
+        """Boolean mask for coefficients with known magnitude
+        (boolean nd-array).
 
         Not defined for int or float entries.
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if magnitude is known.
+        Boolean array with entries set to True if magnitude is known.
 
         Raises
         ------
@@ -518,13 +500,11 @@ class MadArray(np.ndarray):
     @property
     def unknown_magnitude_mask(self):
         """Boolean mask for coefficients with unknown magnitude
+        (boolean nd-array).
 
         Not defined for int or float entries.
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if magnitude is unknown.
+        Boolean array with entries set to True if magnitude is unknown.
 
         Raises
         ------
@@ -536,15 +516,13 @@ class MadArray(np.ndarray):
 
     @property
     def unknown_phase_only_mask(self):
-        """Boolean mask for coefficients with unknown phase and known magnitude.
+        """Boolean mask for coefficients with unknown phase and known magnitude
+        (boolean nd-array).
 
         Not defined for int or float entries.
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if phase is unknown and
-            magnitude is known.
+        Boolean array with entries set to True if phase is unknown and
+        magnitude is known.
 
         Raises
         ------
@@ -556,15 +534,13 @@ class MadArray(np.ndarray):
 
     @property
     def unknown_magnitude_only_mask(self):
-        """Boolean mask for coefficients with unknown magnitude and known phase.
+        """Boolean mask for coefficients with unknown magnitude and known phase
+        (boolean nd-array).
 
         Not defined for int or float entries.
 
-        Returns
-        -------
-        boolean nd-array
-            Boolean array with entries set to True if magnitude is unknown and
-            phase is known.
+        Boolean array with entries set to True if magnitude is unknown and
+        phase is known.
 
         Raises
         ------
@@ -576,15 +552,11 @@ class MadArray(np.ndarray):
 
     @property
     def n_missing_data(self):
-        """Number of missing data.
-
-        Returns
-        -------
-        double or tuple
-            Number of masked coefficients if dtype is int or float. Number of
-            masked coefficients in phase and magnitude masks if dtype is
-            complex.
+        """Number of missing data (double or tuple).
 
+        Number of masked coefficients if dtype is int or float. Number of
+        masked coefficients in phase and magnitude masks if dtype is
+        complex.
         """
         if self._complex_masking:
             return (np.sum(self.unknown_magnitude_mask),
@@ -594,15 +566,11 @@ class MadArray(np.ndarray):
 
     @property
     def ratio_missing_data(self):
-        """Ratio of missing data.
-
-        Returns
-        -------
-        double or tuple
-            Ratio of masked coefficients if dtype is int or float. Ratio of
-            masked coefficients in phase and magnitude masks if dtype is
-            complex.
+        """Ratio of missing data (double or tuple).
 
+        Ratio of masked coefficients if dtype is int or float. Ratio of
+        masked coefficients in phase and magnitude masks if dtype is
+        complex.
         """
         if self._complex_masking:
             return (np.average(self.unknown_magnitude_mask),

madarrays/waveform.py

@@ -217,11 +217,7 @@ class Waveform(MadArray):
 
     @property
     def rms(self):
-        """Root mean square error of the masked signal.
-
-        Returns
-        -------
-        float
+        """Root mean square error of the masked signal (float).
 
         Raises
         ------