Correct the docstrings of selection functions

MDANSE/Src/MDANSE/Framework/AtomSelector/atom_selection.py

@@ -21,14 +21,23 @@
 
 
 def select_atoms(trajectory: Trajectory, **function_parameters: Dict[str, Any]) -> Set[int]:
-    """Selects all the atoms in the trajectory.
+    """Selects specific atoms in the trajectory. These can be selected based
+    on indices, atom type or trajectory-specific atom name.
+    The atom type is normally the chemical element, while
+    the atom name can be more specific and depend on the
+    force field used.
 
     Parameters
     ----------
-    selection : Set[int]
-        A set of atom indices
     trajectory : Trajectory
         A trajectory instance to which the selection is applied
+    function_parameters : Dict[str, Any]
+        may include any combination of the following
+        "index_list" : List[int]
+        "index_range" : a start, stop pair of indices for range(start, stop)
+        "index_slice" : s start, stop, step sequence of indices for range(start, stop, step)
+        "atom_types" : List[str]
+        "atom_names" : List[str]
 
     Returns
     -------
@@ -45,9 +54,9 @@ def select_atoms(trajectory: Trajectory, **function_parameters: Dict[str, Any])
     index_slice = function_parameters.get("index_slice")
     if index_list is not None:
         selection |= indices & index_list
-    elif index_range is not None:
+    if index_range is not None:
         selection |= indices & set(range(*index_range))
-    elif index_slice is not None:
+    if index_slice is not None:
         selection |= indices & set(range(*index_slice))
     atom_types = function_parameters.get("atom_types", ())
     if atom_types:

MDANSE/Src/MDANSE/Framework/AtomSelector/general_selection.py

@@ -24,8 +24,6 @@ def select_all(trajectory: Trajectory, **function_parameters: Dict[str, Any]) ->
 
     Parameters
     ----------
-    selection : Set[int]
-        A set of atom indices
     trajectory : Trajectory
         A trajectory instance to which the selection is applied
 
@@ -42,10 +40,8 @@ def select_none(trajectory: Trajectory, **function_parameters: Dict[str, Any]) -
 
     Parameters
     ----------
-    selection : Set[int]
-        A set of atom indices
     trajectory : Trajectory
-        A trajectory instance to which the selection is applied
+        A trajectory instance, ignored in this selection
 
     Returns
     -------
@@ -56,6 +52,21 @@ def select_none(trajectory: Trajectory, **function_parameters: Dict[str, Any]) -
 
 
 def invert_selection(trajectory: Trajectory, selection: Set[int]) -> Set[int]:
+    """Returns a set of all the indices that are present in the trajectory
+    and were not included in the input selection.
+
+    Parameters
+    ----------
+    trajectory : Trajectory
+        a trajectory containing atoms to be selected
+    selection : Set[int]
+        set of indices to be excluded from the set of all indices
+
+    Returns
+    -------
+    Set[int]
+        set of all the indices in the trajectory which were not in the selection
+    """
     all_indices = select_all(trajectory)
     inverted = all_indices - selection
     return inverted

MDANSE/Src/MDANSE/Framework/AtomSelector/group_selection.py

@@ -22,14 +22,15 @@
 
 
 def select_labels(trajectory: Trajectory, **function_parameters: Dict[str, Any]) -> Set[int]:
-    """Selects all the atoms in the trajectory.
+    """Selects atoms with a specific label in the trajectory.
+    A residue name can be read as a label by MDANSE.
 
     Parameters
     ----------
-    selection : Set[int]
-        A set of atom indices
     trajectory : Trajectory
         A trajectory instance to which the selection is applied
+    function_parameters : Dict[str, Any]
+        should include a list of string labels under key "atom_labels"
 
     Returns
     -------
@@ -46,14 +47,17 @@ def select_labels(trajectory: Trajectory, **function_parameters: Dict[str, Any])
 
 
 def select_pattern(trajectory: Trajectory, **function_parameters: Dict[str, Any]) -> Set[int]:
-    """Selects all the atoms in the trajectory.
+    """Selects atoms according to the SMARTS string given as input.
+    This will only work if molecules and bonds have been detected in the system.
+    If the bond information was not read from the input trajectory on conversion,
+    it can still be determined in a TrajectoryEditor run.
 
     Parameters
     ----------
-    selection : Set[int]
-        A set of atom indices
     trajectory : Trajectory
         A trajectory instance to which the selection is applied
+    function_parameters : Dict[str, Any]
+        should include a SMARTS string under key "rdkit_pattern"
 
     Returns
     -------

MDANSE/Src/MDANSE/Framework/AtomSelector/molecule_selection.py

@@ -22,14 +22,14 @@
 
 
 def select_molecules(trajectory: Trajectory, **function_parameters: Dict[str, Any]) -> Set[int]:
-    """Selects all the atoms in the trajectory.
+    """Selects all the atoms belonging to the specified molecule types.
 
     Parameters
     ----------
-    selection : Set[int]
-        A set of atom indices
     trajectory : Trajectory
         A trajectory instance to which the selection is applied
+    function_parameters : Dict[str, Any]
+        should include a list of str molecule names under key "atom_labels"
 
     Returns
     -------