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

@@ -388,11 +388,8 @@ 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.
@@ -404,11 +401,8 @@ 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.
@@ -420,13 +414,11 @@ 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.
 
@@ -440,13 +432,11 @@ 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.
 
@@ -460,13 +450,10 @@ 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.
 
         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,13 +482,11 @@ 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.
 
         Raises
@@ -518,12 +500,10 @@ 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.
 
         Raises
@@ -536,13 +516,11 @@ 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.
 
@@ -556,13 +534,11 @@ 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.
 
@@ -576,15 +552,11 @@ class MadArray(np.ndarray):
 
     @property
     def n_missing_data(self):
-        """Number of missing data.
+        """Number of missing data (double or tuple).
 
-        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.
-
         """
         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.
+        """Ratio of missing data (double or tuple).
 
-        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.
-
         """
         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
         ------