Add missing documentation for core modules

Author: AndrewSazonov

pyproject.toml

@@ -162,8 +162,9 @@ close-quotes-on-newline = true
 # https://interrogate.readthedocs.io/en/latest/
 
 [tool.interrogate]
-fail-under = 35 # Temporarily reduce to allow gradual improvement
+fail-under = 35                  # Temporarily reduce to allow gradual improvement
 verbose = 1
+exclude = ["src/**/__init__.py"]
 
 #######################################
 # Configuration for coverage/pytest-cov

src/easydiffraction/core/diagnostic.py

@@ -1,24 +1,28 @@
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
+"""Diagnostics helpers for logging validation messages.
+
+This module centralizes human-friendly error and debug logs for
+attribute validation and configuration checks.
+"""
 
 import difflib
 
 from easydiffraction import log
 
 
 class Diagnostics:
-    """Centralized logger for attribute errors and validation
-    guidance.
-    """
+    """Centralized logger for attribute errors and validation hints."""
 
     # ==============================================================
     # Configuration / definition diagnostics
     # ==============================================================
 
     @staticmethod
     def type_override_error(cls_name: str, expected, got):
-        """Report an invalid DataTypes override between descriptor and
-        AttributeSpec.
+        """Report an invalid DataTypes override.
+
+        Used when descriptor and AttributeSpec types conflict.
         """
         expected_label = str(expected)
         got_label = str(got)
@@ -38,6 +42,7 @@ def readonly_error(
         name: str,
         key: str | None = None,
     ):
+        """Log an attempt to change a read-only attribute."""
         Diagnostics._log_error(
             f"Cannot modify read-only attribute '{key}' of <{name}>.",
             exc_type=AttributeError,
@@ -50,6 +55,9 @@ def attr_error(
         allowed: set[str],
         label='Allowed',
     ):
+        """Log access to an unknown attribute and suggest closest
+        key.
+        """
         suggestion = Diagnostics._build_suggestion(key, allowed)
         # Use consistent (label) logic for allowed
         hint = suggestion or Diagnostics._build_allowed(allowed, label=label)
@@ -70,6 +78,7 @@ def type_mismatch(
         current=None,
         default=None,
     ):
+        """Log a type mismatch and keep current or default value."""
         got_type = type(value).__name__
         msg = (
             f'Type mismatch for <{name}>. '
@@ -88,6 +97,7 @@ def range_mismatch(
         current=None,
         default=None,
     ):
+        """Log range violation for a numeric value."""
         msg = f'Value mismatch for <{name}>. Provided {value!r} outside [{ge}, {le}].'
         Diagnostics._log_error_with_fallback(
             msg, current=current, default=default, exc_type=TypeError
@@ -101,6 +111,7 @@ def choice_mismatch(
         current=None,
         default=None,
     ):
+        """Log an invalid choice against allowed values."""
         msg = f'Value mismatch for <{name}>. Provided {value!r} is unknown.'
         if allowed is not None:
             msg += Diagnostics._build_allowed(allowed, label='Allowed values')
@@ -116,6 +127,7 @@ def regex_mismatch(
         current=None,
         default=None,
     ):
+        """Log a regex mismatch with the expected pattern."""
         msg = (
             f"Value mismatch for <{name}>. Provided {value!r} does not match pattern '{pattern}'."
         )
@@ -125,20 +137,24 @@ def regex_mismatch(
 
     @staticmethod
     def no_value(name, default):
+        """Log that default will be used due to missing value."""
         Diagnostics._log_debug(f'No value provided for <{name}>. Using default {default!r}.')
 
     @staticmethod
     def none_value(name):
+        """Log explicit None provided by a user."""
         Diagnostics._log_debug(f'Using `None` explicitly provided for <{name}>.')
 
     @staticmethod
     def none_value_skip_range(name):
+        """Log that range validation is skipped due to None."""
         Diagnostics._log_debug(
             f'Skipping range validation as `None` is explicitly provided for <{name}>.'
         )
 
     @staticmethod
     def validated(name, value, stage: str | None = None):
+        """Log that a value passed a validation stage."""
         stage_info = f' {stage}' if stage else ''
         Diagnostics._log_debug(f'Value {value!r} for <{name}> passed{stage_info} validation.')
 
@@ -148,6 +164,7 @@ def validated(name, value, stage: str | None = None):
 
     @staticmethod
     def _log_error(msg, exc_type=Exception):
+        """Emit an error-level message via shared logger."""
         log.error(message=msg, exc_type=exc_type)
 
     @staticmethod
@@ -157,6 +174,7 @@ def _log_error_with_fallback(
         default=None,
         exc_type=Exception,
     ):
+        """Emit an error message and mention kept or default value."""
         if current is not None:
             msg += f' Keeping current {current!r}.'
         else:
@@ -165,6 +183,7 @@ def _log_error_with_fallback(
 
     @staticmethod
     def _log_debug(msg):
+        """Emit a debug-level message via shared logger."""
         log.debug(message=msg)
 
     # ==============================================================
@@ -173,6 +192,7 @@ def _log_debug(msg):
 
     @staticmethod
     def _suggest(key: str, allowed: set[str]):
+        """Suggest closest allowed key using string similarity."""
         if not allowed:
             return None
         # Return the allowed key with smallest Levenshtein distance

src/easydiffraction/core/identity.py

@@ -1,13 +1,16 @@
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
+"""Identity helpers to build CIF-like hierarchical names.
+
+Used by containers and items to expose datablock/category/entry names
+without tight coupling.
+"""
 
 from typing import Callable
 
 
 class Identity:
-    """Hierarchical identity resolver for datablock/category/entry
-    relationships.
-    """
+    """Resolve datablock/category/entry relationships lazily."""
 
     def __init__(
         self,
@@ -45,24 +48,30 @@ def _resolve_up(self, attr: str, visited=None):
 
     @property
     def datablock_entry_name(self):
+        """Datablock entry name or None if not set."""
         return self._resolve_up('datablock_entry')
 
     @datablock_entry_name.setter
     def datablock_entry_name(self, func: callable):
+        """Set callable returning datablock entry name."""
         self._datablock_entry = func
 
     @property
     def category_code(self):
+        """Category code like 'atom_site' or 'background'."""
         return self._resolve_up('category_code')
 
     @category_code.setter
     def category_code(self, value: str):
+        """Set category code value."""
         self._category_code = value
 
     @property
     def category_entry_name(self):
+        """Category entry name or None if not set."""
         return self._resolve_up('category_entry')
 
     @category_entry_name.setter
     def category_entry_name(self, func: callable):
+        """Set callable returning category entry name."""
         self._category_entry = func

src/easydiffraction/core/validation.py

@@ -1,5 +1,10 @@
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
+"""Lightweight runtime validation utilities.
+
+Provides DataTypes, type/content validators, and AttributeSpec used by
+descriptors and parameters. Only documentation was added here.
+"""
 
 import functools
 import re
@@ -42,9 +47,10 @@ def expected_type(self):
 
 
 def checktype(func=None, *, context=None):
-    """Minimal wrapper to perform runtime type checking and log errors.
+    """Runtime type check decorator using typeguard.
 
-    Optionally prepends context to log message.
+    When a TypeCheckError occurs, the error is logged and None is
+    returned. If context is provided, it is added to the message.
     """
 
     def decorator(f):
@@ -104,11 +110,12 @@ def _fallback(
         current=None,
         default=None,
     ):
+        """Return current if set, else default."""
         return current if current is not None else default
 
 
 class TypeValidator(ValidatorBase):
-    """Ensures a value is of the expected Python type."""
+    """Ensure a value is of the expected Python type."""
 
     def __init__(self, expected_type: DataTypes):
         if isinstance(expected_type, DataTypes):
@@ -125,6 +132,10 @@ def validated(
         current=None,
         allow_none=False,
     ):
+        """Validate type and return value or fallback.
+
+        If allow_none is True, None bypasses content checks.
+        """
         # Fresh initialization, use default
         if current is None and value is None:
             Diagnostics.no_value(name, default)
@@ -155,7 +166,7 @@ def validated(
 
 
 class RangeValidator(ValidatorBase):
-    """Ensures a numeric value lies within [ge, le]."""
+    """Ensure a numeric value lies within [ge, le]."""
 
     def __init__(
         self,
@@ -172,6 +183,7 @@ def validated(
         default=None,
         current=None,
     ):
+        """Validate range and return value or fallback."""
         if not (self.ge <= value <= self.le):
             Diagnostics.range_mismatch(
                 name,
@@ -192,11 +204,9 @@ def validated(
 
 
 class MembershipValidator(ValidatorBase):
-    """Ensures that a value belongs to a predefined list of allowed
-    choices.
+    """Ensure that a value is among allowed choices.
 
-    `allowed` can be a static iterable or a callable returning allowed
-    values.
+    `allowed` may be an iterable or a callable returning a collection.
     """
 
     def __init__(self, allowed):
@@ -210,6 +220,7 @@ def validated(
         default=None,
         current=None,
     ):
+        """Validate membership and return value or fallback."""
         # Dynamically evaluate allowed if callable (e.g. lambda)
         allowed_values = self.allowed() if callable(self.allowed) else self.allowed
 
@@ -232,9 +243,7 @@ def validated(
 
 
 class RegexValidator(ValidatorBase):
-    """Ensures that a string value matches a given regular
-    expression.
-    """
+    """Ensure that a string matches a given regular expression."""
 
     def __init__(self, pattern):
         self.pattern = re.compile(pattern)
@@ -246,6 +255,7 @@ def validated(
         default=None,
         current=None,
     ):
+        """Validate regex and return value or fallback."""
         if not self.pattern.fullmatch(value):
             Diagnostics.regex_mismatch(
                 name,
@@ -265,7 +275,7 @@ def validated(
 
 
 class AttributeSpec:
-    """Holds metadata and validators for a single attribute."""
+    """Hold metadata and validators for a single attribute."""
 
     def __init__(
         self,
@@ -288,6 +298,11 @@ def validated(
         name,
         current=None,
     ):
+        """Validate through type and content validators.
+
+        Returns validated value, possibly default or current if errors
+        occur. None may short-circuit further checks when allowed.
+        """
         val = value
         # Evaluate callable defaults dynamically
         default = self.default() if callable(self.default) else self.default

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

@@ -1,5 +1,9 @@
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
+"""Chebyshev polynomial background model.
+
+Provides a collection of polynomial terms and evaluation helpers.
+"""
 
 from __future__ import annotations
 
@@ -96,6 +100,7 @@ def calculate(self, x_data):
         return y_data
 
     def show(self) -> None:
+        """Print a table of polynomial orders and coefficients."""
         columns_headers: List[str] = ['Order', 'Coefficient']
         columns_alignment = ['left', 'left']
         columns_data: List[List[Union[int, float]]] = [

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

@@ -1,20 +1,25 @@
 # SPDX-FileCopyrightText: 2021-2025 EasyDiffraction contributors <https://github.com/easyscience/diffraction>
 # SPDX-License-Identifier: BSD-3-Clause
+"""Enumerations for background model types."""
 
 from __future__ import annotations
 
 from enum import Enum
 
 
 class BackgroundTypeEnum(str, Enum):
+    """Supported background model types."""
+
     LINE_SEGMENT = 'line-segment'
     CHEBYSHEV = 'chebyshev polynomial'
 
     @classmethod
     def default(cls) -> 'BackgroundTypeEnum':
+        """Return a default background type."""
         return cls.LINE_SEGMENT
 
     def description(self) -> str:
+        """Human-friendly description for the enum value."""
         if self is BackgroundTypeEnum.LINE_SEGMENT:
             return 'Linear interpolation between points'
         elif self is BackgroundTypeEnum.CHEBYSHEV: