From c20b5ba59a7ad8a5e2d0e3e727acf77f79727ebc Mon Sep 17 00:00:00 2001
From: jvonrick <jan.vonrickenbach@ansys.com>
Date: Mon, 2 Sep 2024 11:05:20 +0200
Subject: [PATCH] Improve comments

---
 .../dpf/post/result_workflows/_build_workflow.py    |  5 ++++-
 .../result_workflows/_connect_workflow_inputs.py    | 13 +++++++++++--
 src/ansys/dpf/post/result_workflows/_utils.py       |  2 ++
 3 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/src/ansys/dpf/post/result_workflows/_build_workflow.py b/src/ansys/dpf/post/result_workflows/_build_workflow.py
index b07db8586..5fed82625 100644
--- a/src/ansys/dpf/post/result_workflows/_build_workflow.py
+++ b/src/ansys/dpf/post/result_workflows/_build_workflow.py
@@ -119,7 +119,10 @@ def _create_result_workflows(
     create_operator_callable: _CreateOperatorCallable,
     create_workflow_inputs: _CreateWorkflowInputs,
 ) -> ResultWorkflows:
-    """Internal function to create the result workflows. Use _create_result_workflows instead."""
+    """Creates all the sub-workflows needed to compute a result.
+
+    The resulting workflows are stored in a ResultWorkflows object.
+    """
     initial_result_wf = _create_initial_result_workflow(
         name=create_workflow_inputs.base_name,
         server=server,
diff --git a/src/ansys/dpf/post/result_workflows/_connect_workflow_inputs.py b/src/ansys/dpf/post/result_workflows/_connect_workflow_inputs.py
index bcead62c2..47242bd87 100644
--- a/src/ansys/dpf/post/result_workflows/_connect_workflow_inputs.py
+++ b/src/ansys/dpf/post/result_workflows/_connect_workflow_inputs.py
@@ -6,7 +6,7 @@
 from ansys.dpf.post.selection import Selection, _WfNames
 
 
-def _connect_cyclic_inputs(expand_cyclic, phase_angle_cyclic, result_wf):
+def _connect_cyclic_inputs(expand_cyclic, phase_angle_cyclic, result_wf: Workflow):
     if expand_cyclic is not False:
         # If expand_cyclic is a list
         if isinstance(expand_cyclic, list) and len(expand_cyclic) > 0:
@@ -80,6 +80,11 @@ def _connect_initial_results_inputs(
     streams_provider: Any,
     data_sources: Any,
 ):
+    """Connects the inputs of the initial result workflow.
+
+    The initial result workflow is the first workflow in the result workflows chain, which
+    extracts the raw results from the data sources.
+    """
     initial_result_workflow.connect_with(
         selection.spatial_selection._selection,
         output_input_names={"scoping": "mesh_scoping"},
@@ -118,12 +123,16 @@ def _connect_initial_results_inputs(
 def _connect_averaging_eqv_and_principal_workflows(
     result_workflows: ResultWorkflows,
 ):
+    """Connects the averaging, equivalent, and principal workflows.
+
+    The order of these workflows depends on result_workflows.compute_equivalent_before_average.
+    Only one of equivalent_workflow or principal_workflow can be active at the same time.
+    """
     averaging_wf_connections = {
         _WfNames.output_data: _WfNames.input_data,
         _WfNames.skin: _WfNames.skin,
         _WfNames.skin_input_mesh: _WfNames.skin_input_mesh,
     }
-    # Only one of equivalent_workflow or principal_workflow can be active at the same time.
     assert not (
         result_workflows.equivalent_workflow is not None
         and result_workflows.principal_workflow is not None
diff --git a/src/ansys/dpf/post/result_workflows/_utils.py b/src/ansys/dpf/post/result_workflows/_utils.py
index 22cd57b39..82387ebc2 100644
--- a/src/ansys/dpf/post/result_workflows/_utils.py
+++ b/src/ansys/dpf/post/result_workflows/_utils.py
@@ -6,6 +6,8 @@
 
 
 class _CreateOperatorCallable(Protocol):
+    # Callable to create an operator with a given name.
+    # This usually corresponds to model.operator
     def __call__(self, name: str) -> Operator:
         ...