refine docstring and test comments

Author: yucongalicechen

src/diffpy/utils/tools.py

@@ -136,29 +136,29 @@ def get_package_info(package_names, metadata=None):
 
 
 def compute_mu_using_xraydb(sample_composition, energy, density=None, packing_fraction=1):
-    """
-    Compute the attenuation coefficient (mu) using the XrayDB database
+    """Compute the attenuation coefficient (mu) using the XrayDB database.
 
-    This function calculates mu based on the sample composition and energy.
+    Computes mu based on the sample composition and energy.
     If density is not provided, a standard reference density (e.g., 0.987 g/cm^3 for H2O) is used.
     User can provide either a measured density or an estimated packing fraction (with a standard density).
     It is recommended to specify the density, especially for materials like ZrO2, where it can vary.
-    Reference: https://xraypy.github.io/XrayDB/python.html#xraydb.material_mu
+    Reference: https://xraypy.github.io/XrayDB/python.html#xraydb.material_mu.
 
     Parameters
     ----------
-    sample_composition: str
-        The chemical formula or the name of the material
-    energy: float
-        The energy in eV
-    density: float, optional, Default is None
+    sample_composition : str
+        The chemical formula or the name of the material.
+    energy : float
+        The energy in eV.
+    density : float, optional, Default is None
         The mass density of the packed powder/sample in gr/cm^3. If None, a standard density from XrayDB is used.
-    packing_fraction: float, optional, Default is 1
-        The fraction of sample in the capillary (between 0 and 1)
+    packing_fraction : float, optional, Default is 1
+        The fraction of sample in the capillary (between 0 and 1).
 
     Returns
     -------
-    the attenuation coefficient mu in mm^{-1}
+    mu : float
+        The attenuation coefficient mu in mm^{-1}.
     """
     mu = material_mu(sample_composition, energy, density=density, kind="total") * packing_fraction / 10
     return mu

tests/test_tools.py

@@ -191,25 +191,63 @@ def test_get_package_info(monkeypatch, inputs, expected):
     assert actual_metadata == expected
 
 
-params_mu = [
-    # C1: user didn't specify density or packing fraction
-    ({"sample_composition": "H2O", "energy": 10000, "density": None, "packing_fraction": 1}, 0.5330),
-    # C2: user specified packing fraction only
-    ({"sample_composition": "H2O", "energy": 10000, "density": None, "packing_fraction": 0.5}, 0.2665),
-    # C3: user specified density only
-    ({"sample_composition": "H2O", "energy": 10000, "density": 0.997, "packing_fraction": 1}, 0.5330),
-    ({"sample_composition": "H2O", "energy": 10000, "density": 0.4985, "packing_fraction": 1}, 0.2665),
-    # C4: user specified a standard density and a packing fraction
-    ({"sample_composition": "H2O", "energy": 10000, "density": 0.997, "packing_fraction": 0.5}, 0.2665),
-]
-
-
-@pytest.mark.parametrize("inputs, expected", params_mu)
-def test_compute_mu_using_xraydb(inputs, expected):
+@pytest.mark.parametrize(
+    "inputs, expected_mu",
+    [
+        # Test whether the function returns the correct mu
+        (  # C1: No density or packing fraction provided, expect to compute mu based on standard density
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": None,
+                "packing_fraction": 1,
+            },
+            0.5330,
+        ),
+        (  # C2: Packing fraction (=0.5) provided only, expect to return half of mu based on standard density
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": None,
+                "packing_fraction": 0.5,
+            },
+            0.2665,
+        ),
+        (  # C3: Density provided only, expect to compute mu based on density
+            # 1. Standard density provided, expect to return the same mu as C1
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": 0.997,
+                "packing_fraction": 1,
+            },
+            0.5330,
+        ),
+        (  # 2. Lower density for H2O (half of standard), expect to return half of mu based on standard density
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": 0.4985,
+                "packing_fraction": 1,
+            },
+            0.2665,
+        ),
+        (  # C4: Both standard density and packing fraction are provided, expect to compute the same mu as C2
+            {
+                "sample_composition": "H2O",
+                "energy": 10000,
+                "density": 0.997,
+                "packing_fraction": 0.5,
+            },
+            0.2665,
+        ),
+    ],
+)
+def test_compute_mu_using_xraydb(inputs, expected_mu):
     actual_mu = compute_mu_using_xraydb(
         inputs["sample_composition"],
         inputs["energy"],
         density=inputs["density"],
         packing_fraction=inputs["packing_fraction"],
     )
-    assert actual_mu == pytest.approx(expected, rel=0.01, abs=0.1)
+    assert actual_mu == pytest.approx(expected_mu, rel=0.01, abs=0.1)