docs: update and clarify docstrings with examples and type hints (#971)

docs: update and clarify docstrings with examples and type hints

- Expanded docstrings with usage examples and improved clarity  
- Added missing type hints  
- Addressed review feedback and cleaned up documentation

Author: MAfarrag

hydrolib/tools/extforce_convert/cli.py

@@ -16,8 +16,19 @@
 )
 
 
-def valid_file(path_str):
-    """Check if the file exists, has a .mdu extension, and return its path."""
+def valid_file(path_str: str):
+    """Validate an .mdu file path and return it as a Path object.
+
+    Args:
+        path_str (str):
+            The path to the MDU file as provided on the command line.
+
+    Returns:
+        Path: The validated path to the file.
+
+    Raises:
+        argparse.ArgumentTypeError: If the file does not exist or does not have a .mdu extension.
+    """
     path = Path(path_str)
     if not str(path).lower().endswith(".mdu"):
         raise ArgumentTypeError(f"File must have a .mdu extension: {path}")
@@ -27,8 +38,21 @@ def valid_file(path_str):
     return path
 
 
-def _validator(path_str, extension):
-    """Validate that the file exists and has the given extension."""
+def _validator(path_str: str, extension: str):
+    """Validate that a file exists and matches the expected extension.
+
+    Args:
+        path_str (str):
+            The path to the file to validate.
+        extension (str):
+            The required file extension (including the dot), e.g. ".ext".
+
+    Returns:
+        Path: The validated file path.
+
+    Raises:
+        argparse.ArgumentTypeError: If the file does not exist or the extension does not match.
+    """
     path = Path(path_str)
     if not path.exists():
         raise ArgumentTypeError(f"File not found: {path}")
@@ -37,13 +61,36 @@ def _validator(path_str, extension):
     return path
 
 
-def valid_file_with_extension(extension):
-    """Create a validator for files with a specific extension for argparse."""
+def valid_file_with_extension(extension: str):
+    """Create a validator callable for argparse that enforces a file extension.
+
+    Args:
+        extension (str):
+            The required file extension (including the dot), e.g. ".mdu".
+
+    Returns:
+        Callable[[str], Path]:
+            A function that validates a path string and returns a Path when invoked.
+
+    Raises:
+        argparse.ArgumentTypeError: Raised by the returned validator if the provided path does not exist or
+            does not end with the required extension.
+    """
     return lambda path_str: _validator(path_str, extension)
 
 
-def valid_dir(path_str):
-    """Validate that the path exists and is a directory."""
+def valid_dir(path_str: str):
+    """Validate that the given path exists and is a directory.
+
+    Args:
+        path_str (str): The path to validate.
+
+    Returns:
+        Path: The validated directory path.
+
+    Raises:
+        argparse.ArgumentTypeError: If the path does not exist or is not a directory.
+    """
     path = Path(path_str)
     if not path.exists():
         raise ArgumentTypeError(f"Directory not found: {path}")
@@ -53,6 +100,11 @@ def valid_dir(path_str):
 
 
 def _get_parser() -> argparse.ArgumentParser:
+    """Create and configure the argument parser for the extforce_convert CLI.
+
+    Returns:
+        argparse.ArgumentParser: The configured argument parser.
+    """
     parser = argparse.ArgumentParser(
         prog="extforce_convert",
         description="Convert D-Flow FM legacy external forcings files to current external forcings file/initial fields file/structures file.",
@@ -137,32 +189,63 @@ def _get_parser() -> argparse.ArgumentParser:
 
 def main(args=None):
     """
-    Entry point for extforce_convert tool.
+    Entry point for the extforce_convert command-line tool.
 
     CLI argument combinations:
 
     Required (mutually exclusive, pick one):
-      --mdufile MDUFILE         Use MDUFILE to determine input/output files automatically.
-      --extoldfile EXTOLDFILE   Convert a specific legacy external forcing file.
-      --dir DIR                 Recursively find and convert all .mdu files in DIR.
+      --mdufile, -m MDUFILE         Use MDUFILE to determine input/output files automatically.
+      --extoldfile, -e EXTOLDFILE   Convert a specific legacy external forcing file.
+      --dir, -d DIR                 Recursively find and convert all .mdu files in DIR.
 
     Optional:
-      --outfiles EXTFILE INIFIELDFILE STRUCTUREFILE
+      --outfiles, -o EXTFILE INIFIELDFILE STRUCTUREFILE
                                Specify output filenames for forcings, initial fields, and structures (only with --mdufile or --extoldfile).
-      --no-backup              Do not create a backup of overwritten files (mutually exclusive).
-      --remove-legacy-files -r Remove legacy/old files (e.g. .tim) after conversion.
-      --verbose, -v            Print diagnostic information.
-      --version                Print version and exit.
+                               Note: requires exactly three paths and is only valid for single-file conversions
+                               (i.e., when using --mdufile or --extoldfile). Using --outfiles with --dir is invalid
+                               and will result in an error.
+      --no-backup                  Do not create a backup of overwritten files.
+      --remove-legacy-files, -r    Remove legacy/old files (e.g. .tim) after conversion.
+      --debug-mode                 Convert only supported quantities; leave unsupported quantities in the legacy external forcing file (default: False).
+      --verbose, -v                Print diagnostic information.
+      --version                    Print version and exit.
       --path-style {unix,windows}
-                               Handle absolute paths in input/output files according to the specified style (unix/windows).
-                               Use this when converting models that use unix paths but you are running the converter
-                               on a Windows machine and the opposite.
-
-    Example usages:
-      extforce_convert --mdufile model.mdu
-      extforce_convert --extoldfile old.ext --outfiles new.ext new.ini new.str
-      extforce_convert --dir ./models --no-backup --remove-legacy-files
-      extforce_convert --mdufile model.mdu --path-style unix
+                                 Handle absolute paths in input/output files according to the specified style (unix/windows).
+                                 Use this when converting models that use unix paths but you are running the converter
+                                 on a Windows machine, or the opposite.
+
+    Args:
+      args (Optional[List[str]]): Optional list of argument strings to parse instead of sys.argv. Useful for testing.
+
+    Notes:
+      - `--outfiles` cannot be combined with `--dir`.
+      - `--outfiles` applies only to a single conversion target (from --mdufile or --extoldfile) and must provide three
+        filenames, in this order: EXTFILE INIFIELDFILE STRUCTUREFILE.
+      - When `--debug-mode` is provided, only supported quantities are converted; unsupported quantities remain in the
+        legacy external forcing file. Without this flag, encountering unsupported quantities results in a failure.
+
+    Examples (valid):
+        - Use an MDU file and let the tool determine I/O automatically
+            ```shell
+            >>> extforce_convert --mdufile model.mdu # doctest: +SKIP
+            ```
+        - Convert a specific legacy .ext and explicitly set output filenames
+            ```shell
+            >>> extforce_convert --extoldfile old.ext --outfiles new.ext new.ini new.str # doctest: +SKIP
+            ```
+        - Recursively convert all models in a directory (no --outfiles here)
+            ```shell
+            >>> extforce_convert --dir ./models --no-backup --remove-legacy-files # doctest: +SKIP
+            ```
+        - Convert with explicit path style handling
+            ```shell
+            >>> extforce_convert --mdufile model.mdu --path-style unix # doctest: +SKIP
+            ```
+        - invalid flags combinations that will raise an error:
+            --outfiles only works with single-file modes, not with --dir
+            ```shell
+            >>> extforce_convert --dir ./models --outfiles a.ext b.ini c.str # doctest: +SKIP
+            ```
     """
     parser = _get_parser()
     args = parser.parse_args(args)