Merge pull request #307 from yucongalicechen/docstring

docs: add docstrings for on_d, on_q, on_tth, and dump

Author: sbillinge

news/DO-docstring.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* docstrings for `on_q`, `on_tth`, `on_d`, and `dump` in `diffraction_objects.py`.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/utils/diffraction_objects.py

@@ -418,12 +418,33 @@ def _get_original_array(self):
             return self.on_d(), "d"
 
     def on_q(self):
+        """Return the tuple of two 1D numpy arrays containing q and y data.
+
+        Returns
+        -------
+        (q-array, y-array) : tuple of ndarray
+            The tuple containing two 1D numpy arrays with q and y data
+        """
         return [self.all_arrays[:, 1], self.all_arrays[:, 0]]
 
     def on_tth(self):
+        """Return the tuple of two 1D numpy arrays containing tth and y data.
+
+        Returns
+        -------
+        (tth-array, y-array) : tuple of ndarray
+            The tuple containing two 1D numpy arrays with tth and y data
+        """
         return [self.all_arrays[:, 2], self.all_arrays[:, 0]]
 
     def on_d(self):
+        """Return the tuple of two 1D numpy arrays containing d and y data.
+
+        Returns
+        -------
+        (d-array, y-array) : tuple of ndarray
+            The tuple containing two 1D numpy arrays with d and y data
+        """
         return [self.all_arrays[:, 3], self.all_arrays[:, 0]]
 
     def scale_to(self, target_diff_object, q=None, tth=None, d=None, offset=None):
@@ -507,6 +528,34 @@ def on_xtype(self, xtype):
             raise ValueError(_xtype_wmsg(xtype))
 
     def dump(self, filepath, xtype=None):
+        """Dump the xarray and yarray of the diffraction object to a two-column
+        file, with the associated information included in the header.
+
+        Parameters
+        ----------
+        filepath : str
+            The filepath where the diffraction object will be dumped
+        xtype : str, optional, default is q
+            The type of quantity for the independent variable chosen from {*XQUANTITIES, }
+
+        Examples
+        --------
+        To save a diffraction object to a file named "diffraction_data.chi" in the current directory
+        with the independent variable 'q':
+
+        >>> file = "diffraction_data.chi"
+        >>> do.dump(file, xtype="q")
+
+        To save the diffraction data to a file in a subfolder `output`:
+
+        >>> file = "./output/diffraction_data.chi"
+        >>> do.dump(file, xtype="q")
+
+        To save the diffraction data with a different independent variable, such as 'tth':
+
+        >>> file = "diffraction_data_tth.chi"
+        >>> do.dump(file, xtype="tth")
+        """
         if xtype is None:
             xtype = "q"
         if xtype in QQUANTITIES: