add/edit docstrings for metadata_merge.py and validator.py (#408)

* docstrings

* docstrings

* lints

cubids/metadata_merge.py

@@ -1,4 +1,8 @@
-"""Tools for merging metadata."""
+"""Metadata merging utilities for CuBIDS.
+
+This module provides utilities for merging metadata in CuBIDS, including functions
+for checking merging operations, grouping acquisitions, and handling metadata fields.
+"""
 
 import json
 from collections import defaultdict
@@ -179,15 +183,44 @@ def merge_without_overwrite(source_meta, dest_meta_orig, raise_on_error=False):
 
 
 def is_nan(val):
-    """Return True if val is NaN."""
+    """Check if the given value is NaN (Not a Number).
+
+    Parameters
+    ----------
+    val : any
+        The value to check.
+
+    Returns
+    -------
+    bool
+        True if the value is NaN, False otherwise.
+    """
     if not isinstance(val, float):
         return False
 
     return isnan(val)
 
 
 def print_merges(merge_list):
-    """Print formatted text of merges."""
+    """Print formatted text of merges.
+
+    Parameters
+    ----------
+    merge_list : list of tuple
+        A list of tuples where each tuple contains two elements:
+
+        - src_id : tuple
+            The source identifier, where the last element is the source ID and
+            the first element is the source name.
+        - dest_id : tuple
+            The destination identifier, where the last element is the destination
+            ID and the first element is the destination name.
+
+    Returns
+    -------
+    str
+        A formatted string representing the merges, with each merge on a new line.
+    """
     merge_strings = []
     for src_id, dest_id in merge_list:
         src_id_str = f"{src_id[-1]}:{src_id[0]}"

cubids/validator.py

@@ -1,4 +1,8 @@
-"""Methods for validating BIDS datasets."""
+"""Methods for validating BIDS datasets.
+
+This module provides functions for validating BIDS datasets, including building
+subprocess commands for the BIDS validator and handling validation results.
+"""
 
 import glob
 import json
@@ -60,7 +64,24 @@ def get_bids_validator_version():
 
 
 def build_subject_paths(bids_dir):
-    """Build a list of BIDS dirs with 1 subject each."""
+    """Build a dictionary of BIDS directories with one subject each.
+
+    Parameters
+    ----------
+    bids_dir : str
+        The root directory of the BIDS dataset.
+
+    Returns
+    -------
+    dict
+        A dictionary where the keys are subject labels and the values are
+        lists of file paths associated with each subject.
+
+    Raises
+    ------
+    ValueError
+        If no subjects are found in the specified directory.
+    """
     bids_dir = str(bids_dir)
     if not bids_dir.endswith("/"):
         bids_dir += "/"
@@ -88,7 +109,21 @@ def build_subject_paths(bids_dir):
 
 
 def build_first_subject_path(bids_dir, subject):
-    """Build a list of BIDS dirs with 1 subject each."""
+    """Build a dictionary containing BIDS directory paths for a single subject.
+
+    Parameters
+    ----------
+    bids_dir : str
+        The root directory of the BIDS dataset.
+    subject : str
+        The path to the subject directory.
+
+    Returns
+    -------
+    dict
+        A dictionary where the key is the subject label and the value is a list of file paths
+        within the subject directory and the root BIDS directory.
+    """
     bids_dir = str(bids_dir)
     if not bids_dir.endswith("/"):
         bids_dir += "/"
@@ -224,7 +259,7 @@ def extract_summary_info(output):
 
 
 def update_dataset_description(path, new_info):
-    """Update or append information to dataset_description.json.
+    """Update or append information to dataset_description.json with new information.
 
     Parameters
     ----------