doc: add docs

Author: msto

latch/resources/workflow.py

@@ -141,6 +141,17 @@ def decorator(f: Callable):
 
 def _is_valid_samplesheet_parameter_type(parameter: inspect.Parameter) -> bool:
     """Check if a workflow parameter is hinted with a valid type for a samplesheet LatchParameter.
+
+    Currently, a samplesheet LatchParameter must be defined as a list of dataclasses, or as an
+    `Optional` list of dataclasses when the parameter is part of a `ForkBranch`.
+
+    Args:
+        parameter: A parameter from the workflow function's signature.
+
+    Returns:
+        True if the parameter is annotated as a list of dataclasses, or as an `Optional` list of
+        dataclasses.
+        False otherwise.
     """
     annotation = parameter.annotation
 
@@ -165,7 +176,7 @@ def _is_list_of_dataclasses_type(dtype: TypeAnnotation) -> bool:
         False otherwise.
 
     Raises:
-        TypeError: If the input is not a `type`.
+        TypeError: If the input is not a valid `TypeAnnotation` type (see above).
     """
     if not isinstance(dtype, TYPE_ANNOTATION_TYPES):
         raise TypeError(f"Expected `type`, got {type(dtype)}: {dtype}")
@@ -196,7 +207,7 @@ def _is_optional_type(dtype: TypeAnnotation) -> bool:
         False otherwise.
 
     Raises:
-        TypeError: If the input is not a `type`.
+        TypeError: If the input is not a valid `TypeAnnotation` type (see above).
     """
     if not isinstance(dtype, TYPE_ANNOTATION_TYPES):
         raise TypeError(f"Expected `type`, got {type(dtype)}: {dtype}")
@@ -223,7 +234,7 @@ def _unpack_optional_type(dtype: TypeAnnotation) -> type:
         The type `T`.
 
     Raises:
-        TypeError: If the input is not a `type`.
+        TypeError: If the input is not a valid `TypeAnnotation` type (see above).
         ValueError: If the input type is not `Optional[T]`.
     """
     if not isinstance(dtype, TYPE_ANNOTATION_TYPES):
@@ -243,25 +254,27 @@ def _unpack_optional_type(dtype: TypeAnnotation) -> type:
     return base_type
 
 
+# NB: `inspect.Parameter.annotation` is typed as `Any`, so here we narrow the type.
 def _is_type_annotation(annotation: Any) -> TypeGuard[TypeAnnotation]:
     """Check if the annotation on an `inspect.Parameter` instance is a type annotation.
 
     If the corresponding parameter **did not** have a type annotation, `annotation` is set to the
-    special class variable `Parameter.empty`.
-
-    NB: `Parameter.empty` itself is a subclass of `type`
-    Otherwise, the annotation is assumed to be a type.
+    special class variable `inspect.Parameter.empty`. Otherwise, the annotation should be a valid
+    type annotation.
 
     Args:
         annotation: The annotation on an `inspect.Parameter` instance.
 
     Returns:
-        True if the annotation is not `Parameter.empty`.
+        True if the type annotation is not `inspect.Parameter.empty`.
         False otherwise.
 
     Raises:
-        TypeError: If the annotation is neither a type nor `Parameter.empty`.
+        TypeError: If the annotation is neither a valid `TypeAnnotation` type (see above) nor
+        `inspect.Parameter.empty`.
     """
+    # NB: `inspect.Parameter.empty` is a subclass of `type`, so this check passes for unannotated
+    # parameters.
     if not isinstance(annotation, TYPE_ANNOTATION_TYPES):
         raise TypeError(f"Annotation must be a type, not {type(annotation).__name__}")