docs(util): add module-level docstrings to util package

autogalaxy/util/error_util.py

@@ -1,3 +1,24 @@
+"""
+Utility functions for computing posterior error estimates on 1D profiles and 2D ellipses.
+
+These helpers operate on lists of sampled quantities (e.g. 1D light-profile intensity
+curves or 2D isophote coordinate arrays drawn from a ``PyAutoFit`` posterior PDF) and
+return the median value together with a lower/upper confidence interval computed from
+user-specified quantiles.
+
+Key functions
+-------------
+- ``value_median_and_error_region_via_quantile`` — scalar median + credible interval.
+- ``profile_1d_median_and_error_region_via_quantile`` — per-radial-bin median + interval
+  for 1D profiles (e.g. a convergence or surface-brightness radial profile).
+- ``quantile_profile_1d`` — low-level per-bin quantile computation, adapted from
+  ``corner.py``.
+- ``ellipse_median_and_error_region_via_quantile`` — Cartesian median + interval for 2D
+  isophote coordinate arrays.
+- ``ellipse_median_and_error_region_in_polar`` — same but computed in polar coordinates
+  so that the confidence region is expressed radially rather than in (y, x), which is
+  more robust for highly elongated isophotes.
+"""
 import numpy as np
 
 from autofit.non_linear.samples.pdf import quantile

autogalaxy/util/mock/mock_cosmology.py

@@ -1,8 +1,17 @@
+"""
+Mock cosmology object for use in unit tests.
+
+``MockCosmology`` implements the same interface as the real ``LensingCosmology`` class
+(``autogalaxy/cosmology/model.py``) but returns hard-coded constant values rather than
+calling ``astropy.cosmology``.  This makes unit tests fast and free of external
+dependencies while still exercising code paths that accept a cosmology argument.
+
+The ``Value`` helper wraps a scalar so that ``.to(unit)`` calls (which real astropy
+``Quantity`` objects support) are accepted without error.
+"""
 import math
 import numpy as np
 
-# Mock Cosmology #
-
 
 class Value:
     def __init__(self, value):

autogalaxy/util/shear_field.py

@@ -1,3 +1,26 @@
+"""
+Weak-lensing shear field data structures.
+
+This module extends **PyAutoArray**'s vector-field classes with properties specific to
+weak gravitational lensing.  A *shear field* is a set of (γ₂, γ₁) complex shear
+components stored on a 2D grid; each vector encodes the shape distortion induced on a
+background source galaxy by the intervening mass distribution.
+
+Convention
+----------
+The shear components are stored as ``[γ₂, γ₁]`` (``[:, 0]`` is γ₂, ``[:, 1]`` is γ₁),
+following the standard lensing sign convention where the position angle φ is measured
+counter-clockwise from the positive x-axis.
+
+Two concrete classes are provided:
+
+- ``ShearYX2D`` — regular grid variant (inherits ``aa.VectorYX2D``).
+- ``ShearYX2DIrregular`` — irregular grid variant (inherits ``aa.VectorYX2DIrregular``).
+
+Both classes inherit the shared mixin ``AbstractShearField`` which provides derived
+quantities: ellipticities, semi-major/minor axes, position angles (``phis``), and
+``matplotlib`` ellipse patches for visualization.
+"""
 import logging
 import numpy as np
 import typing