Improve docstrings for dynamic time shift modules

lisainstrument/dynamic_delay_dask.py

 """Functions for applying dynamic real-valued shifts to dask arrays using Lagrange interpolation
 
-Use make_dynamic_shift_lagrange_dask to create a Lagrange interpolator for dask arrays.
+The main class in this module is DynamicShiftDask. It allows to perform a time-shifting
+opration on a dask array, with time-dependent time shift. This class is used in
+lisainstrument.Instrument for applying all non-const delays. For the special case of fixed
+time shifts, see module fixed_shift_dask.
+
+
+The interpolation method to be used is provided by the user in form of an object
+implementing the RegularInterpolator protocol defined in the module
+lisainstrument.regular_interpolators. This interpolation engine is based on numpy
+arrays. It is used for the main work of time-shifting each chunk of data. The
+RegularInterpolator protocol is not responsible for setting up boundary conditions.
+Internal and external boundaries are handled by DynamicShiftDask itself.
+
+The other parameters that determine the DynamicShiftDask behavior are collected
+in a class DynShiftCfg (see module dynamic_delay_numpy). DynShiftCfg includes limits
+for the allowable minimum and maximum time shift. Those have to be supplied by the user
+because they cannot be determined from the data as this would require evaluating the
+whole timeshift dask array before doing the interpolation.
+
+The convenience functions make_dynamic_shift_lagrange_dask() and
+make_dynamic_shift_linear_dask() return a DynamicShiftDask instance
+employing Lagrange or linear interpolation, respectively. For testing,
+there is another Lagrange interpolator based on the legacy dsp.timeshift
+code. Use lisainstrument.dynamic_delay_dsp.make_dynamic_shift_dsp_dask()
+to obtain a corresponding DynamicShiftDask instance.
+
+For testing, there is a function numpyfy_dask_multi() which turns a dask-based
+time-shift operator into one operating on numpy arrays, using dask only internally.
+
+
+Example use:
+
+>>> op = make_dynamic_shift_lagrange_dask(
+        order=31,
+        min_delay=-2., max_delay=21.,
+        left_bound=ShiftBC.FLAT, right_bound=ShiftBC.EXCEPTION
+    )
+>>> delay_dask = da.linspace(-1.2,20.4,100)
+>>> data_dask = da.linspace(0,1, len(delay)
+>>> shifted_data_dask = op(data_dask, -delay_dask)
+
+
+Internally, the module works as follows. DynamicShiftDask contains a
+user-provided RegularInterpolator. The latter can interpolate to points
+within the given data, minus a margin size defined by RegularInterpolator
+implementations. For each chunk of the timeshift, DynamicShiftNumpy
+interpolates the required region of data using RegularInterpolator.
+The size of the required region for a give chunk depends on the margins needed
+by the interpolator as well as the fixed limits specified for the timeshift.
+Further, the outer boundaries of the dask array are padded with margins
+filled according to the selected boundary conditions.
 """
 
 from __future__ import annotations

lisainstrument/dynamic_delay_numpy.py

@@ -22,7 +22,10 @@ is required to behave exactly like DynamicShiftDask.
 
 The convenience functions make_dynamic_shift_lagrange_numpy() and
 make_dynamic_shift_linear_numpy() return a DynamicShiftNumpy instance
-employing Lagrange or linear interpolation, respectively.
+employing Lagrange or linear interpolation, respectively. For testing,
+there is another Lagrange interpolator based on the legacy dsp.timeshift
+code. Use lisainstrument.dynamic_delay_dsp.make_dynamic_shift_dsp_numpy()
+to obtain a corresponding DynamicShiftNumpy instance.
 
 Example use: