Updated the docs on tools/, scripts/, validator

Author: VisLab

docs/api/tools.rst

@@ -14,6 +14,30 @@ EventManager
    :undoc-members:
    :show-inheritance:
 
+EventChecker
+~~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.event_checker.EventChecker
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+EventsChecker
+~~~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.event_checker.EventsChecker
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+EventsSummary
+~~~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.events_summary.EventsSummary
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 HedTagManager
 ~~~~~~~~~~~~~
 
@@ -22,6 +46,22 @@ HedTagManager
    :undoc-members:
    :show-inheritance:
 
+HedTagCount
+~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.hed_tag_counts.HedTagCount
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HedTagCounts
+~~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.hed_tag_counts.HedTagCounts
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 HedTypeManager
 ~~~~~~~~~~~~~~
 
@@ -30,6 +70,46 @@ HedTypeManager
    :undoc-members:
    :show-inheritance:
 
+HedType
+~~~~~~~
+
+.. autoclass:: hed.tools.analysis.hed_type.HedType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HedTypeDefs
+~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.hed_type_defs.HedTypeDefs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HedTypeFactors
+~~~~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.hed_type_factors.HedTypeFactors
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HedTypeCount
+~~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.hed_type_counts.HedTypeCount
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HedTypeCounts
+~~~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.hed_type_counts.HedTypeCounts
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 TabularSummary
 ~~~~~~~~~~~~~~
 
@@ -38,10 +118,10 @@ TabularSummary
    :undoc-members:
    :show-inheritance:
 
-HedType
-~~~~~~~
+ColumnNameSummary
+~~~~~~~~~~~~~~~~~
 
-.. autoclass:: hed.tools.analysis.hed_type.HedType
+.. autoclass:: hed.tools.analysis.column_name_summary.ColumnNameSummary
    :members:
    :undoc-members:
    :show-inheritance:
@@ -54,6 +134,29 @@ FileDictionary
    :undoc-members:
    :show-inheritance:
 
+KeyMap
+~~~~~~
+
+.. autoclass:: hed.tools.analysis.key_map.KeyMap
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+TemporalEvent
+~~~~~~~~~~~~~
+
+.. autoclass:: hed.tools.analysis.temporal_event.TemporalEvent
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Annotation utilities
+~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: hed.tools.analysis.annotation_util
+   :members:
+   :undoc-members:
+
 BIDS tools
 ----------
 
@@ -101,5 +204,29 @@ BIDS utilities
 ~~~~~~~~~~~~~~
 
 .. automodule:: hed.tools.bids.bids_util
-   :members: parse_bids_filename
+   :members:
+   :undoc-members:
+
+Utility functions
+-----------------
+
+DataFrame utilities
+~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: hed.tools.util.data_util
+   :members:
+   :undoc-members:
+
+File/IO utilities
+~~~~~~~~~~~~~~~~~
+
+.. automodule:: hed.tools.util.io_util
+   :members:
+   :undoc-members:
+
+Schema utilities
+~~~~~~~~~~~~~~~~
+
+.. automodule:: hed.tools.util.schema_util
+   :members:
    :undoc-members:

docs/api/validator.rst

@@ -49,6 +49,74 @@ OnsetValidator
    :undoc-members:
    :show-inheritance:
 
+ReservedChecker
+~~~~~~~~~~~~~~~
+
+.. autoclass:: hed.validator.reserved_checker.ReservedChecker
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Validator utilities
+-------------------
+
+CharValidator
+~~~~~~~~~~~~~
+
+.. autoclass:: hed.validator.util.char_util.CharValidator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+CharRexValidator
+~~~~~~~~~~~~~~~~
+
+.. autoclass:: hed.validator.util.char_util.CharRexValidator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+UnitValueValidator
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: hed.validator.util.class_util.UnitValueValidator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+DuplicateChecker
+~~~~~~~~~~~~~~~~
+
+.. autoclass:: hed.validator.util.dup_util.DuplicateChecker
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+GroupValidator
+~~~~~~~~~~~~~~
+
+.. autoclass:: hed.validator.util.group_util.GroupValidator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+StringValidator
+~~~~~~~~~~~~~~~
+
+.. autoclass:: hed.validator.util.string_util.StringValidator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+TagValidator
+~~~~~~~~~~~~
+
+.. autoclass:: hed.validator.util.tag_util.TagValidator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
 Validation utilities
 --------------------
 

hed/scripts/__init__.py

@@ -0,0 +1 @@
+"""Legacy CLI entry point scripts (deprecated — prefer the ``hedpy`` CLI)."""

hed/scripts/add_hed_ids.py

@@ -1,3 +1,5 @@
+"""CLI script to add missing HED IDs to a schema in the hed-schemas repository."""
+
 from hed.scripts.schema_script_util import get_prerelease_path
 from hed.scripts.hed_convert_schema import convert_and_update
 import argparse
@@ -6,6 +8,12 @@
 
 # Slightly tweaked version of hed_convert_schema.py with a new main function to allow different parameters.
 def main():
+    """Entry point: parse arguments and add HED IDs to the specified schema version.
+
+    Returns:
+        int: 0 on success, non-zero on failure.
+
+    """
     parser = argparse.ArgumentParser(description="Add hed ids to a specific schema.")
     parser.add_argument("repo_path", help="The location of the hed-schemas directory")
     parser.add_argument("schema_name", help='The name of the schema("standard" for standard schema) to modify')

hed/scripts/hed_convert_schema.py

@@ -1,3 +1,5 @@
+"""CLI script to validate and convert HED schema files across formats (XML, MediaWiki, TSV, JSON)."""
+
 from hed.scripts.schema_script_util import sort_base_schemas, validate_all_schemas, add_extension
 from hed.schema.schema_io import load_dataframes, save_dataframes
 from hed.schema.schema_io.hed_id_util import update_dataframes_from_schema
@@ -76,6 +78,15 @@ def convert_and_update(filenames, set_ids):
 
 
 def main(arg_list=None):
+    """Entry point: parse arguments and convert/validate the named schema files.
+
+    Parameters:
+        arg_list (list[str] or None): Argument list for testing; uses sys.argv if None.
+
+    Returns:
+        int: 0 on success, non-zero if validation fails.
+
+    """
     parser = argparse.ArgumentParser(description="Update other schema formats based on the changed one.")
     parser.add_argument("filenames", nargs="*", help="List of files to process")
     parser.add_argument("--set-ids", action="store_true", help="Add missing HED ids")

hed/scripts/schema_script_util.py

@@ -1,3 +1,5 @@
+"""Shared utilities for schema validation, sorting, and format conversion used by CLI scripts."""
+
 import os.path
 from collections import defaultdict
 from hed.schema import from_string, load_schema, from_dataframes

hed/scripts/validate_bids.py

@@ -196,6 +196,15 @@ def format_final_report(issue_list):
 
 
 def main(arg_list=None):
+    """Entry point: parse arguments, validate the BIDS dataset, and print a summary report.
+
+    Parameters:
+        arg_list (list[str] or None): Argument list for testing; uses sys.argv if None.
+
+    Returns:
+        int: 0 if no issues found, 1 if validation issues are present.
+
+    """
     # Create the argument parser
     parser = get_parser()
 
@@ -231,6 +240,16 @@ def main(arg_list=None):
 
 
 def validate_dataset(args):
+    """Run HED validation on the BIDS dataset described by args and return the issue list.
+
+    Parameters:
+        args (argparse.Namespace): Parsed CLI arguments including data_path, suffixes, and
+            check_for_warnings.
+
+    Returns:
+        list[dict]: Validation issue dictionaries (empty list if no issues).
+
+    """
     logger = logging.getLogger("validate_bids")
     logger.info(f"Data directory: {args.data_path}")
     logger.info(f"HEDTools version: {__version__}")

hed/scripts/validate_schemas.py

@@ -1,3 +1,5 @@
+"""CLI script to validate HED schema files for compliance and format consistency."""
+
 import sys
 from hed.scripts.schema_script_util import validate_all_schemas, sort_base_schemas
 from hed.errors import get_printable_issue_string
@@ -20,6 +22,15 @@ def get_parser():
 
 
 def main(arg_list=None):
+    """Entry point: parse arguments and validate the specified schema files.
+
+    Parameters:
+        arg_list (list[str] or None): Argument list for testing; uses sys.argv if None.
+
+    Returns:
+        int: 0 if all schemas are valid, 1 if any issues are found.
+
+    """
     parser = get_parser()
     args = parser.parse_args(arg_list)
 

hed/tools/analysis/event_checker.py

@@ -1,9 +1,13 @@
+"""Checker that validates event-level HED annotation quality for BIDS datasets."""
+
 from hed.errors.error_types import TagQualityErrors
 from hed.errors import ErrorHandler, ErrorContext, sort_issues
 from hed.tools import EventManager, HedTagManager
 
 
 class EventChecker:
+    """Validates that HED-annotated events meet quality requirements such as having a top-level event tag."""
+
     EVENT_TAGS = {
         "Event",
         "Sensory-event",