docs: improve docstring based on group standards in diffraction_objects.py transforms.py

Author: bobleesj

doc/source/api/diffpy.utils.parsers.rst

@@ -11,14 +11,6 @@ diffpy.utils.parsers package
 Submodules
 ----------
 
-diffpy.utils.parsers.serialization module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: diffpy.utils.parsers.serialization
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 diffpy.utils.parsers.loaddata module
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -34,3 +26,11 @@ diffpy.utils.parsers.custom_exceptions module
     :members:
     :undoc-members:
     :show-inheritance:
+
+diffpy.utils.parsers.serialization module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.utils.parsers.serialization
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/api/diffpy.utils.rst

@@ -16,40 +16,46 @@ Subpackages
 
     diffpy.utils.parsers
     diffpy.utils.wx
-    diffpy.utils.scattering_objects
 
 Submodules
 ----------
 
-diffpy.utils.tools module
-^^^^^^^^^^^^^^^^^^^^^^^^^
+diffpy.utils.transforms module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: diffpy.utils.tools
+.. automodule:: diffpy.utils.transforms
     :members:
     :undoc-members:
     :show-inheritance:
 
-diffpy.utils.resampler module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+diffpy.utils.tools module
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: diffpy.utils.resampler
+.. automodule:: diffpy.utils.tools
     :members:
     :undoc-members:
     :show-inheritance:
 
-
 diffpy.utils.user_config module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. automodule:: diffpy.utils.user_config
     :members:
     :undoc-members:
     :show-inheritance:
 
 diffpy.utils.diffraction_objects module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. automodule:: diffpy.utils.diffraction_objects
     :members:
     :undoc-members:
     :show-inheritance:
+
+diffpy.utils.resampler module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.utils.resampler
+    :members:
+    :undoc-members:
+    :show-inheritance:

news/docstrings-refactor.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* No news added: this branch was used to refactor the docstrings in the codebase without adding new features
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/utils/diffraction_objects.py

@@ -92,18 +92,18 @@ def __init__(
             The dependent variable array corresponding to intensity values.
         xtype : str
             The type of the independent variable in `xarray`. Must be one of {*XQUANTITIES}.
-        wavelength : float, optional
-            The wavelength of the incoming beam, specified in angstroms (Å). Default is none.
-        scat_quantity : str, optional
-            The type of scattering experiment (e.g., "x-ray", "neutron"). Default is an empty string "".
-        name : str, optional
-            The name or label for the scattering data. Default is an empty string "".
-        metadata : dict, optional
-            The additional metadata associated with the diffraction object. Default is {}.
+        wavelength : float, optional, default is None.
+            The wavelength of the incoming beam, specified in angstroms (Å)
+        scat_quantity : str, optional, default is an empty string "".
+            The type of scattering experiment (e.g., "x-ray", "neutron").
+        name : str, optional, default is an empty string "".
+            The name or label for the scattering data.
+        metadata : dict, optional, default is an empty dictionary {}
+            The additional metadata associated with the diffraction object.
 
         Examples
         --------
-        Create a DiffractionObject for X-ray scattering data
+        Create a DiffractionObject for X-ray scattering data:
         >>> import numpy as np
         >>> from diffpy.utils.diffraction_objects import DiffractionObject
         ...
@@ -180,30 +180,32 @@ def __add__(self, other):
 
         Parameters
         ----------
-        other : DiffractionObject or int or float
-            The object to add to the current DiffractionObject. If `other` is a scalar value,
-            it will be added to all yarray. The length of the yarray must match if `other` is
-            an instance of DiffractionObject.
+        other : DiffractionObject, int, or float
+            The item to be added. If `other` is a scalar value, this value will be added to each element of the
+            yarray of this DiffractionObject instance. If `other` is another DiffractionObject, the yarrays of the
+            two DiffractionObjects will be combined element-wise. The result is a new DiffractionObject instance,
+            representing the addition and using the xarray from the left-hand side DiffractionObject.
 
         Returns
         -------
         DiffractionObject
-            The new and deep-copied DiffractionObject instance after adding values to the yarray.
+            THe new DiffractionObject instance with modified yarray values. This instance is a deep copy of the
+            original with the additions applied.
 
         Raises
         ------
         ValueError
-            Raised when the length of the yarray of the two DiffractionObject instances do not match.
+            Raised when the xarrays of two DiffractionObject instances are not equal.
         TypeError
-            Raised when the type of `other` is not an instance of DiffractionObject, int, or float.
+            Raised when `other` is not an instance of DiffractionObject, int, or float.
 
         Examples
         --------
-        Add a scalar value to the yarray of the DiffractionObject instance:
+        Add a scalar value to the yarray of a DiffractionObject instance:
         >>> new_do = my_do + 10.1
         >>> new_do = 10.1 + my_do
 
-        Add the yarray of two DiffractionObject instances:
+        Combine the yarrays of two DiffractionObject instances:
         >>> new_do = my_do_1 + my_do_2
         """
 
@@ -218,6 +220,21 @@ def __add__(self, other):
     __radd__ = __add__
 
     def __sub__(self, other):
+        """Subtract scalar value or another DiffractionObject to the yarray of
+        the DiffractionObject.
+
+        This method behaves similarly to the `__add__` method, but performs subtraction instead of addition.
+        For details on parameters, returns, and exceptions, refer to the documentation for `__add__`.
+
+        Examples
+        --------
+        Subtract a scalar value from the yarray of a DiffractionObject instance:
+        >>> new_do = my_do - 10.1
+
+        Subtract the yarrays of two DiffractionObject instances:
+        >>> new_do = my_do_1 - my_do_2
+        """
+
         self._check_operation_compatibility(other)
         subtracted_do = deepcopy(self)
         if isinstance(other, (int, float)):
@@ -229,6 +246,21 @@ def __sub__(self, other):
     __rsub__ = __sub__
 
     def __mul__(self, other):
+        """Multiply a scalar value or another DiffractionObject with the yarray
+        of this DiffractionObject.
+
+        This method behaves similarly to the `__add__` method, but performs multiplication instead of addition.
+        For details on parameters, returns, and exceptions, refer to the documentation for `__add__`.
+
+        Examples
+        --------
+        Multiply a scalar value with the yarray of a DiffractionObject instance:
+        >>> new_do = my_do * 3.5
+
+        Multiply the yarrays of two DiffractionObject instances:
+        >>> new_do = my_do_1 * my_do_2
+        """
+
         self._check_operation_compatibility(other)
         multiplied_do = deepcopy(self)
         if isinstance(other, (int, float)):
@@ -240,6 +272,20 @@ def __mul__(self, other):
     __rmul__ = __mul__
 
     def __truediv__(self, other):
+        """Divide the yarray of this DiffractionObject by a scalar value or
+        another DiffractionObject.
+
+        This method behaves similarly to the `__add__` method, but performs division instead of addition.
+        For details on parameters, returns, and exceptions, refer to the documentation for `__add__`.
+
+        Examples
+        --------
+        Divide the yarray of a DiffractionObject instance by a scalar value:
+        >>> new_do = my_do / 2.0
+
+        Divide the yarrays of two DiffractionObject instances:
+        >>> new_do = my_do_1 / my_do_2
+        """
         self._check_operation_compatibility(other)
         divided_do = deepcopy(self)
         if isinstance(other, (int, float)):
@@ -288,7 +334,7 @@ def input_xtype(self):
 
         Returns
         -------
-        str
+        input_xtype : str
             The type of `xarray`, which must be one of {*XQUANTITIES}.
         """
         return self._input_xtype
@@ -303,7 +349,7 @@ def uuid(self):
 
         Returns
         -------
-        uuid
+        uuid : UUID
             The unique identifier of the DiffractionObject instance.
         """
         return self._uuid
@@ -325,7 +371,7 @@ def get_array_index(self, xtype, xvalue):
 
         Returns
         -------
-        int
+        index : int
             The index of the closest value in the array associated with the specified xtype and the value provided.
         """
 
@@ -378,7 +424,7 @@ def on_d(self):
         return [self.all_arrays[:, 3], self.all_arrays[:, 0]]
 
     def scale_to(self, target_diff_object, q=None, tth=None, d=None, offset=None):
-        """Returns a new diffraction object which is the current object but
+        """Return a new diffraction object which is the current object but
         rescaled in y to the target.
 
         By default, if `q`, `tth`, or `d` are not provided, scaling is based on the max intensity from each object.
@@ -400,12 +446,12 @@ def scale_to(self, target_diff_object, q=None, tth=None, d=None, offset=None):
 
         Returns
         -------
-        scaled : DiffractionObject
+        scaled_do : DiffractionObject
             The rescaled DiffractionObject as a new object.
         """
         if offset is None:
             offset = 0
-        scaled = self.copy()
+        scaled_do = self.copy()
         count = sum([q is not None, tth is not None, d is not None])
         if count > 1:
             raise ValueError(
@@ -416,8 +462,8 @@ def scale_to(self, target_diff_object, q=None, tth=None, d=None, offset=None):
         if count == 0:
             q_target_max = max(target_diff_object.on_q()[1])
             q_self_max = max(self.on_q()[1])
-            scaled._all_arrays[:, 0] = scaled._all_arrays[:, 0] * q_target_max / q_self_max + offset
-            return scaled
+            scaled_do._all_arrays[:, 0] = scaled_do._all_arrays[:, 0] * q_target_max / q_self_max + offset
+            return scaled_do
 
         xtype = "q" if q is not None else "tth" if tth is not None else "d"
         data = self.on_xtype(xtype)
@@ -427,21 +473,26 @@ def scale_to(self, target_diff_object, q=None, tth=None, d=None, offset=None):
 
         xindex_data = (np.abs(data[0] - xvalue)).argmin()
         xindex_target = (np.abs(target[0] - xvalue)).argmin()
-        scaled._all_arrays[:, 0] = data[1] * target[1][xindex_target] / data[1][xindex_data] + offset
-        return scaled
+        scaled_do._all_arrays[:, 0] = data[1] * target[1][xindex_target] / data[1][xindex_data] + offset
+        return scaled_do
 
     def on_xtype(self, xtype):
-        """Return a list of two 1D np array with x and y data, raise an error
-        if the specified xtype is invalid.
+        """Return a tuple of two 1D numpy arrays containing x and y data.
 
         Parameters
         ----------
-        xtype str
-            the type of quantity for the independent variable from {*XQUANTITIES, }
+        xtype : str
+            The type of quantity for the independent variable chosen from {*XQUANTITIES, }
+
+        Raises
+        ------
+        ValueError
+            Raised when the specified xtype is not among {*XQUANTITIES, }
 
         Returns
         -------
-        a list of two 1D np array with x and y data
+        (xarray, yarray) : tuple of ndarray
+            A tuple containing two 1D numpy arrays with x and y data for the specified xtype.
         """
         if xtype.lower() in ANGLEQUANTITIES:
             return self.on_tth()
@@ -482,6 +533,6 @@ def copy(self):
         Returns
         -------
         DiffractionObject
-            A new instance of DiffractionObject, which is a deep copy of the current instance.
+            The new instance of DiffractionObject, which is a deep copy of the current instance.
         """
         return deepcopy(self)