Enhances documentation with docstrings

Author: AndrewSazonov

src/easydiffraction/analysis/calculators/factory.py

@@ -17,6 +17,14 @@
 
 
 class CalculatorFactory:
+    """Factory for creating calculation engine instances.
+
+    The factory exposes discovery helpers to list and show available
+    calculators in the current environment and a creator that returns an
+    instantiated calculator or ``None`` if the requested one is not
+    available.
+    """
+
     _potential_calculators: Dict[str, Dict[str, Union[str, Type[CalculatorBase]]]] = {
         'crysfml': {
             'description': 'CrysFML library for crystallographic calculations',
@@ -36,6 +44,14 @@ class CalculatorFactory:
     def _supported_calculators(
         cls,
     ) -> Dict[str, Dict[str, Union[str, Type[CalculatorBase]]]]:
+        """Return calculators whose engines are importable.
+
+        This filters the list of potential calculators by instantiating
+        their classes and checking the ``engine_imported`` property.
+
+        Returns:
+            Mapping from calculator name to its config dict.
+        """
         return {
             name: cfg
             for name, cfg in cls._potential_calculators.items()
@@ -44,10 +60,16 @@ def _supported_calculators(
 
     @classmethod
     def list_supported_calculators(cls) -> List[str]:
+        """List names of calculators available in the environment.
+
+        Returns:
+            List of calculator identifiers, e.g. ``["crysfml", ...]``.
+        """
         return list(cls._supported_calculators().keys())
 
     @classmethod
     def show_supported_calculators(cls) -> None:
+        """Pretty-print supported calculators and their descriptions."""
         columns_headers: List[str] = ['Calculator', 'Description']
         columns_alignment = ['left', 'left']
         columns_data: List[List[str]] = []
@@ -64,6 +86,14 @@ def show_supported_calculators(cls) -> None:
 
     @classmethod
     def create_calculator(cls, calculator_name: str) -> Optional[CalculatorBase]:
+        """Create a calculator instance by name.
+
+        Args:
+            calculator_name: Identifier of the calculator to create.
+
+        Returns:
+            A calculator instance or ``None`` if unknown or unsupported.
+        """
         config = cls._supported_calculators().get(calculator_name)
         if not config:
             print(error(f"Unknown calculator '{calculator_name}'"))

src/easydiffraction/analysis/fit_helpers/reporting.py

@@ -14,6 +14,13 @@
 
 
 class FitResults:
+    """Container for results of a single optimization run.
+
+    Holds success flag, chi-square metrics, iteration counts, timing,
+    and parameter objects. Provides a printer to summarize key
+    indicators and a table of fitted parameters.
+    """
+
     def __init__(
         self,
         success: bool = False,
@@ -27,6 +34,22 @@ def __init__(
         fitting_time: Optional[float] = None,
         **kwargs: Any,
     ) -> None:
+        """Initialize FitResults with the given parameters.
+
+        Args:
+            success: Indicates if the fit was successful.
+            parameters: List of parameters used in the fit.
+            chi_square: Chi-square value of the fit.
+            reduced_chi_square: Reduced chi-square value of the fit.
+            message: Message related to the fit.
+            iterations: Number of iterations performed.
+            engine_result: Result from the fitting engine.
+            starting_parameters: Initial parameters for the fit.
+            fitting_time: Time taken for the fitting process.
+            **kwargs: Additional engine-specific fields. If ``redchi``
+                is provided and ``reduced_chi_square`` is not set, it is
+                used as the reduced chi-square value.
+        """
         self.success: bool = success
         self.parameters: List[Any] = parameters if parameters is not None else []
         self.chi_square: Optional[float] = chi_square
@@ -54,6 +77,15 @@ def display_results(
         f_obs: Optional[List[float]] = None,
         f_calc: Optional[List[float]] = None,
     ) -> None:
+        """Render a human-readable summary of the fit.
+
+        Args:
+            y_obs: Observed intensities for pattern R-factor metrics.
+            y_calc: Calculated intensities for pattern R-factor metrics.
+            y_err: Standard deviations of observed intensities for wR.
+            f_obs: Observed structure-factor magnitudes for Bragg R.
+            f_calc: Calculated structure-factor magnitudes for Bragg R.
+        """
         status_icon = '✅' if self.success else '❌'
         rf = rf2 = wr = br = None
         if y_obs is not None and y_calc is not None:

src/easydiffraction/analysis/fit_helpers/tracking.py

@@ -42,8 +42,11 @@ def format_cell(
 
 
 class FitProgressTracker:
-    """Tracks and reports the reduced chi-square during the optimization
-    process.
+    """Track and report reduced chi-square during optimization.
+
+    The tracker keeps iteration counters, remembers the best observed
+    reduced chi-square and when it occurred, and can display progress as
+    a table in notebooks or a text UI in terminals.
     """
 
     def __init__(self) -> None:
@@ -59,6 +62,7 @@ def __init__(self) -> None:
         self._display_handle: Optional[DisplayHandle] = None
 
     def reset(self) -> None:
+        """Reset internal state before a new optimization run."""
         self._iteration = 0
         self._previous_chi2 = None
         self._last_chi2 = None
@@ -72,15 +76,14 @@ def track(
         residuals: np.ndarray,
         parameters: List[float],
     ) -> np.ndarray:
-        """Track chi-square progress during the optimization process.
+        """Update progress with current residuals and parameters.
 
-        Parameters:
-            residuals (np.ndarray): Array of residuals between measured
-                and calculated data.
-            parameters (list): List of free parameters being fitted.
+        Args:
+            residuals: Residuals between measured and calculated data.
+            parameters: Current free parameters being fitted.
 
         Returns:
-            np.ndarray: Residuals unchanged, for optimizer consumption.
+            Residuals unchanged, for optimizer consumption.
         """
         self._iteration += 1
 
@@ -133,28 +136,39 @@ def track(
 
     @property
     def best_chi2(self) -> Optional[float]:
+        """Best recorded reduced chi-square value or None."""
         return self._best_chi2
 
     @property
     def best_iteration(self) -> Optional[int]:
+        """Iteration index at which the best chi-square was observed."""
         return self._best_iteration
 
     @property
     def iteration(self) -> int:
+        """Current iteration counter."""
         return self._iteration
 
     @property
     def fitting_time(self) -> Optional[float]:
+        """Elapsed time of the last run in seconds, if available."""
         return self._fitting_time
 
     def start_timer(self) -> None:
+        """Begin timing of a fit run."""
         self._start_time = time.perf_counter()
 
     def stop_timer(self) -> None:
+        """Stop timing and store elapsed time for the run."""
         self._end_time = time.perf_counter()
         self._fitting_time = self._end_time - self._start_time
 
     def start_tracking(self, minimizer_name: str) -> None:
+        """Initialize display and headers and announce the minimizer.
+
+        Args:
+            minimizer_name: Name of the minimizer used for the run.
+        """
         print(f"🚀 Starting fit process with '{minimizer_name}'...")
         print('📈 Goodness-of-fit (reduced χ²) change:')
 
@@ -189,6 +203,11 @@ def start_tracking(self, minimizer_name: str) -> None:
             print('╞' + '╪'.join(['═' * FIXED_WIDTH for _ in DEFAULT_HEADERS]) + '╡')
 
     def add_tracking_info(self, row: List[str]) -> None:
+        """Append a formatted row to the progress display.
+
+        Args:
+            row: Columns corresponding to DEFAULT_HEADERS.
+        """
         if is_notebook() and display is not None:
             # Add row to DataFrame
             self._df_rows.append(row)
@@ -214,6 +233,7 @@ def add_tracking_info(self, row: List[str]) -> None:
             print(formatted_row)
 
     def finish_tracking(self) -> None:
+        """Finalize progress display and print best result summary."""
         # Add last iteration as last row
         row: List[str] = [
             str(self._last_iteration),

src/easydiffraction/core/collection.py

@@ -1,26 +1,45 @@
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
+"""Lightweight container for guarded items with name-based indexing.
+
+`CollectionBase` maintains an ordered list of items and a lazily rebuilt
+index by the item's identity key. It supports dict-like access for get,
+set and delete, along with iteration over the items.
+"""
 
 from __future__ import annotations
 
 from easydiffraction.core.guard import GuardedBase
 
 
 class CollectionBase(GuardedBase):
+    """A minimal collection with stable iteration and name indexing.
+
+    Args:
+        item_type: Type of items accepted by the collection. Used for
+            validation and tooling; not enforced at runtime here.
+    """
+
     def __init__(self, item_type) -> None:
         super().__init__()
         self._items: list = []
         self._index: dict = {}
         self._item_type = item_type
 
     def __getitem__(self, name: str):
+        """Return an item by its identity key.
+
+        Rebuilds the internal index on a cache miss to stay consistent
+        with recent mutations.
+        """
         try:
             return self._index[name]
         except KeyError:
             self._rebuild_index()
             return self._index[name]
 
     def __setitem__(self, name: str, item) -> None:
+        """Insert or replace an item under the given identity key."""
         # Check if item with same identity exists; if so, replace it
         for i, existing_item in enumerate(self._items):
             if existing_item._identity.category_entry_name == name:
@@ -33,6 +52,7 @@ def __setitem__(self, name: str, item) -> None:
         self._rebuild_index()
 
     def __delitem__(self, name: str) -> None:
+        """Delete an item by key or raise ``KeyError`` if missing."""
         # Remove from _items by identity entry name
         for i, item in enumerate(self._items):
             if item._identity.category_entry_name == name:
@@ -43,32 +63,40 @@ def __delitem__(self, name: str) -> None:
         raise KeyError(name)
 
     def __iter__(self):
+        """Iterate over items in insertion order."""
         return iter(self._items)
 
     def __len__(self) -> int:
+        """Return the number of items in the collection."""
         return len(self._items)
 
     def _key_for(self, item):
-        """Private helper to get the key for an item."""
+        """Return the identity key for ``item`` (category or
+        datablock).
+        """
         return item._identity.category_entry_name or item._identity.datablock_entry_name
 
     def _rebuild_index(self) -> None:
+        """Rebuild the name-to-item index from the ordered item list."""
         self._index.clear()
         for item in self._items:
             key = self._key_for(item)
             if key:
                 self._index[key] = item
 
     def keys(self):
+        """Yield keys for all items in insertion order."""
         return (self._key_for(item) for item in self._items)
 
     def values(self):
+        """Yield items in insertion order."""
         return (item for item in self._items)
 
     def items(self):
+        """Yield ``(key, item)`` pairs in insertion order."""
         return ((self._key_for(item), item) for item in self._items)
 
     @property
     def names(self):
-        """Return a list of all item keys in the collection."""
+        """List of all item keys in the collection."""
         return list(self.keys())

src/easydiffraction/experiments/categories/background/base.py

@@ -10,10 +10,25 @@
 
 
 class BackgroundBase(CategoryCollection):
+    """Abstract base for background subcategories in experiments.
+
+    Concrete implementations provide parameterized background models and
+    compute background intensities on the experiment grid.
+    """
+
     @abstractmethod
     def calculate(self, x_data: Any) -> Any:
+        """Compute background values for the provided x grid.
+
+        Args:
+            x_data: X positions (e.g. 2θ, TOF) at which to evaluate.
+
+        Returns:
+            Background intensity array aligned with ``x_data``.
+        """
         pass
 
     @abstractmethod
     def show(self) -> None:
+        """Print a human-readable view of background components."""
         pass

src/easydiffraction/experiments/categories/instrument/base.py

@@ -7,6 +7,12 @@
 
 
 class InstrumentBase(CategoryItem):
+    """Base class for instrument category items.
+
+    Provides the common identity code and serves as a parent for
+    concrete instrument definitions (CWL/TOF).
+    """
+
     def __init__(self) -> None:
         super().__init__()
         self._identity.category_code = 'instrument'

src/easydiffraction/experiments/categories/instrument/cwl.py

@@ -53,16 +53,20 @@ def __init__(
 
     @property
     def setup_wavelength(self):
+        """Incident wavelength parameter (Å)."""
         return self._setup_wavelength
 
     @setup_wavelength.setter
     def setup_wavelength(self, value):
+        """Set incident wavelength value (Å)."""
         self._setup_wavelength.value = value
 
     @property
     def calib_twotheta_offset(self):
+        """Instrument misalignment two-theta offset (deg)."""
         return self._calib_twotheta_offset
 
     @calib_twotheta_offset.setter
     def calib_twotheta_offset(self, value):
+        """Set two-theta offset value (deg)."""
         self._calib_twotheta_offset.value = value