Docstrings and type hints for reindex_experiments and `reindex_refl…

…ections` (dials#2683)

Add docstrings and type hints for reindex_experiments and reindex_reflections. Fixes dials#2682

newsfragments/2683.bugfix

@@ -0,0 +1,3 @@
+Docstrings and type hints are added to the ``reindex_experiments`` and
+``reindex_reflections`` functions to make it easier to use these
+outside the ``dials.reindex`` program.

src/dials/util/reindex.py

@@ -4,6 +4,7 @@
 import logging
 
 from cctbx import sgtbx
+from dxtbx.model import ExperimentList
 from rstbx.symmetry.constraints import parameter_reduction
 
 from dials.algorithms.scaling.scaling_library import determine_best_unit_cell
@@ -91,9 +92,24 @@ def change_of_basis_op_against_reference(
     return change_of_basis_op
 
 
-def reindex_experiments(experiments, cb_op, space_group=None):
-    reindexed_experiments = copy.deepcopy(experiments)
+def reindex_experiments(
+    experiments: ExperimentList,
+    cb_op: sgtbx.change_of_basis_op,
+    space_group: sgtbx.space_group | None = None,
+) -> ExperimentList:
+    """
+    Reindexes the given experiment list using the provided change of basis operator, and optionally set the space group.
+
+    Args:
+        experiments (ExperimentList): The list of experiments to reindex.
+        cb_op (sgtbx.change_of_basis_op): The change of basis operator.
+        space_group (sgtbx.space_group | None, optional): The space group to set after reindexing. Defaults to None.
+
+    Returns:
+        ExperimentList: The reindexed experiments.
+    """
 
+    reindexed_experiments = copy.deepcopy(experiments)
     for crystal in reindexed_experiments.crystals():
         cryst_reindexed = copy.deepcopy(crystal)
         if space_group is not None:
@@ -123,9 +139,26 @@ def reindex_experiments(experiments, cb_op, space_group=None):
     return reindexed_experiments
 
 
-def reindex_reflections(reflections, change_of_basis_op, hkl_offset=None):
-    reflections = flex.reflection_table.concat(reflections)
+def reindex_reflections(
+    reflections: list[flex.reflection_table],
+    change_of_basis_op: sgtbx.change_of_basis_op,
+    hkl_offset: list[int] | None = None,
+) -> flex.reflection_table:
+    """
+    Reindexes reflection tables based on a change of basis operation and an optional HKL offset.
 
+    Args:
+        reflections (list[flex.reflection_table]): A list of reflection tables to be reindexed.
+        change_of_basis_op (sgtbx.change_of_basis_op): The change of basis operation to apply.
+        hkl_offset (list[int] | None, optional): An optional HKL offset to apply. Defaults to None.
+
+    Returns:
+        flex.reflection_table: The reindexed reflection table.
+
+    Removes reflections whose change of basis results in non-integral indices.
+    """
+
+    reflections = flex.reflection_table.concat(reflections)
     miller_indices = reflections["miller_index"]
 
     if hkl_offset is not None: