Adds docstrings for improved code documentation

Author: AndrewSazonov

src/easydiffraction/analysis/calculators/pdffit.py

@@ -1,3 +1,8 @@
+"""PDF calculation backend using diffpy.pdffit2 if available.
+
+The class adapts the engine to EasyDiffraction calculator interface and
+silences stdio on import to avoid noisy output in notebooks and logs.
+"""
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
 

src/easydiffraction/analysis/categories/aliases.py

@@ -1,3 +1,8 @@
+"""Alias category for mapping friendly names to parameter UIDs.
+
+Defines a small record type used by analysis configuration to refer to
+parameters via readable labels instead of raw unique identifiers.
+"""
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
 
@@ -11,6 +16,17 @@
 
 
 class Alias(CategoryItem):
+    """Single alias entry.
+
+    Maps a human-readable ``label`` to a concrete ``param_uid`` used by
+    the engine.
+
+    Args:
+        label: Alias label. Must match ``^[A-Za-z_][A-Za-z0-9_]*$``.
+        param_uid: Target parameter uid. Same identifier pattern as
+            ``label``.
+    """
+
     def __init__(
         self,
         *,
@@ -57,21 +73,36 @@ def __init__(
 
     @property
     def label(self):
+        """Alias label descriptor."""
         return self._label
 
     @label.setter
     def label(self, value):
+        """Set alias label.
+
+        Args:
+            value: New label.
+        """
         self._label.value = value
 
     @property
     def param_uid(self):
+        """Parameter uid descriptor the alias points to."""
         return self._param_uid
 
     @param_uid.setter
     def param_uid(self, value):
+        """Set the parameter uid.
+
+        Args:
+            value: New uid.
+        """
         self._param_uid.value = value
 
 
 class Aliases(CategoryCollection):
+    """Collection of :class:`Alias` items."""
+
     def __init__(self):
+        """Create an empty collection of aliases."""
         super().__init__(item_type=Alias)

src/easydiffraction/analysis/categories/constraints.py

@@ -1,3 +1,8 @@
+"""Simple symbolic constraint between parameters.
+
+Represents an equation of the form ``lhs_alias = rhs_expr`` where
+``rhs_expr`` is evaluated elsewhere by the analysis engine.
+"""
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
 
@@ -11,6 +16,13 @@
 
 
 class Constraint(CategoryItem):
+    """Single constraint item.
+
+    Args:
+        lhs_alias: Left-hand side alias name being constrained.
+        rhs_expr: Right-hand side expression as a string.
+    """
+
     def __init__(
         self,
         *,
@@ -56,21 +68,36 @@ def __init__(
 
     @property
     def lhs_alias(self):
+        """Alias name on the left-hand side of the equation."""
         return self._lhs_alias
 
     @lhs_alias.setter
     def lhs_alias(self, value):
+        """Set the left-hand side alias.
+
+        Args:
+            value: New alias string.
+        """
         self._lhs_alias.value = value
 
     @property
     def rhs_expr(self):
+        """Right-hand side expression string."""
         return self._rhs_expr
 
     @rhs_expr.setter
     def rhs_expr(self, value):
+        """Set the right-hand side expression.
+
+        Args:
+            value: New expression string.
+        """
         self._rhs_expr.value = value
 
 
 class Constraints(CategoryCollection):
+    """Collection of :class:`Constraint` items."""
+
     def __init__(self):
+        """Create an empty constraints collection."""
         super().__init__(item_type=Constraint)

src/easydiffraction/analysis/categories/joint_fit_experiments.py

@@ -1,3 +1,8 @@
+"""Joint-fit experiment weighting configuration.
+
+Stores per-experiment weights to be used when multiple experiments are
+fitted simultaneously.
+"""
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
 
@@ -13,6 +18,13 @@
 
 
 class JointFitExperiment(CategoryItem):
+    """A single joint-fit entry.
+
+    Args:
+        id: Experiment identifier used in the fit session.
+        weight: Relative weight factor in the combined objective.
+    """
+
     def __init__(
         self,
         *,
@@ -59,25 +71,36 @@ def __init__(
 
     @property
     def id(self):
+        """Experiment identifier descriptor."""
         return self._id
 
     @id.setter
     def id(self, value):
+        """Set the experiment identifier.
+
+        Args:
+            value: New id string.
+        """
         self._id.value = value
 
     @property
     def weight(self):
+        """Weight factor descriptor."""
         return self._weight
 
     @weight.setter
     def weight(self, value):
+        """Set the weight factor.
+
+        Args:
+            value: New weight value.
+        """
         self._weight.value = value
 
 
 class JointFitExperiments(CategoryCollection):
-    """Collection manager for experiments that are fitted together in a
-    `joint` fit.
-    """
+    """Collection of :class:`JointFitExperiment` items."""
 
     def __init__(self):
+        """Create an empty joint-fit experiments collection."""
         super().__init__(item_type=JointFitExperiment)

src/easydiffraction/analysis/minimizers/base.py

@@ -16,9 +16,14 @@
 
 
 class MinimizerBase(ABC):
-    """Abstract base class for minimizer implementations.
-
-    Provides shared logic and structure for concrete minimizers.
+    """Abstract base for concrete minimizers.
+
+    Contract:
+    - Subclasses must implement ``_prepare_solver_args``,
+        ``_run_solver``, ``_sync_result_to_parameters`` and
+        ``_check_success``.
+    - The ``fit`` method orchestrates the full workflow and returns
+        :class:`FitResults`.
     """
 
     def __init__(
@@ -39,18 +44,29 @@ def __init__(
         self.tracker: FitProgressTracker = FitProgressTracker()
 
     def _start_tracking(self, minimizer_name: str) -> None:
+        """Initialize progress tracking and timer.
+
+        Args:
+            minimizer_name: Human-readable name shown in progress.
+        """
         self.tracker.reset()
         self.tracker.start_tracking(minimizer_name)
         self.tracker.start_timer()
 
     def _stop_tracking(self) -> None:
+        """Stop timer and finalize tracking."""
         self.tracker.stop_timer()
         self.tracker.finish_tracking()
 
     @abstractmethod
     def _prepare_solver_args(self, parameters: List[Any]) -> Dict[str, Any]:
-        """Prepare the solver arguments directly from the list of free
-        parameters.
+        """Prepare keyword-arguments for the underlying solver.
+
+        Args:
+            parameters: List of free parameters to be fitted.
+
+        Returns:
+            Mapping of keyword arguments to pass into ``_run_solver``.
         """
         pass
 
@@ -60,6 +76,7 @@ def _run_solver(
         objective_function: Callable[..., Any],
         engine_parameters: Dict[str, Any],
     ) -> Any:
+        """Execute the concrete solver and return its raw result."""
         pass
 
     @abstractmethod
@@ -68,13 +85,25 @@ def _sync_result_to_parameters(
         raw_result: Any,
         parameters: List[Any],
     ) -> None:
+        """Copy values from ``raw_result`` back to ``parameters`` in-
+        place.
+        """
         pass
 
     def _finalize_fit(
         self,
         parameters: List[Any],
         raw_result: Any,
     ) -> FitResults:
+        """Build :class:`FitResults` and store it on ``self.result``.
+
+        Args:
+            parameters: Parameters after the solver finished.
+            raw_result: Backend-specific solver output object.
+
+        Returns:
+            FitResults: Aggregated outcome of the fit.
+        """
         self._sync_result_to_parameters(parameters, raw_result)
         success = self._check_success(raw_result)
         self.result = FitResults(
@@ -89,17 +118,24 @@ def _finalize_fit(
 
     @abstractmethod
     def _check_success(self, raw_result: Any) -> bool:
-        """Determine whether the fit was successful.
-
-        This must be implemented by concrete minimizers.
-        """
+        """Determine whether the fit was successful."""
         pass
 
     def fit(
         self,
         parameters: List[Any],
         objective_function: Callable[..., Any],
     ) -> FitResults:
+        """Run the full minimization workflow.
+
+        Args:
+            parameters: Free parameters to optimize.
+            objective_function: Callable returning residuals for a given
+                set of engine arguments.
+
+        Returns:
+            FitResults with success flag, best chi2 and timing.
+        """
         minimizer_name = self.name or 'Unnamed Minimizer'
         if self.method is not None:
             minimizer_name += f' ({self.method})'
@@ -123,6 +159,7 @@ def _objective_function(
         experiments: Any,
         calculator: Any,
     ) -> np.ndarray:
+        """Default objective helper computing residuals array."""
         return self._compute_residuals(
             engine_params,
             parameters,
@@ -138,6 +175,7 @@ def _create_objective_function(
         experiments: Any,
         calculator: Any,
     ) -> Callable[[Dict[str, Any]], np.ndarray]:
+        """Return a closure capturing problem context for the solver."""
         return lambda engine_params: self._objective_function(
             engine_params,
             parameters,

src/easydiffraction/crystallography/space_groups.py

@@ -1,5 +1,11 @@
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
+"""Space group reference data.
+
+Loads a gzipped, packaged pickle with crystallographic space-group
+information. The file is part of the distribution; user input is not
+involved.
+"""
 
 import gzip
 import pickle  # noqa: S403 - trusted internal pickle file (package data only)
@@ -18,6 +24,7 @@ def _restricted_pickle_load(file_obj) -> Any:
 
 
 def _load():
+    """Load space-group data from the packaged archive."""
     path = Path(__file__).with_name('space_groups.pkl.gz')
     with gzip.open(path, 'rb') as f:
         return _restricted_pickle_load(f)

src/easydiffraction/experiments/categories/excluded_regions.py

@@ -1,5 +1,6 @@
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
+"""Exclude ranges of x from fitting/plotting (masked regions)."""
 
 from typing import List
 
@@ -15,6 +16,8 @@
 
 
 class ExcludedRegion(CategoryItem):
+    """Closed interval [start, end] to be excluded."""
+
     def __init__(
         self,
         *,
@@ -83,8 +86,8 @@ def __init__(self):
         super().__init__(item_type=ExcludedRegion)
 
     def add(self, item: ExcludedRegion) -> None:
-        """Mark excluded points in the experiment pattern when a new
-        region is added.
+        """Mark excluded points in the pattern when a region is
+        added.
         """
         # 1. Call parent add first
 
@@ -106,6 +109,7 @@ def add(self, item: ExcludedRegion) -> None:
         datastore.meas_su = datastore.full_meas_su[~datastore.excluded]
 
     def show(self) -> None:
+        """Print a table of excluded [start, end] intervals."""
         # TODO: Consider moving this to the base class
         #  to avoid code duplication with implementations in Background,
         #  etc. Consider using parameter names as column headers