From ad6f345e64b40fb0b06c3abfc887ac06102ffff5 Mon Sep 17 00:00:00 2001
From: Josh Mitchell <yoshanuikabundi@gmail.com>
Date: Fri, 6 Oct 2023 12:57:56 +1100
Subject: [PATCH] Clarify "DAG dependency order" in docstrings

---
 gufe/protocols/protocoldag.py | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/gufe/protocols/protocoldag.py b/gufe/protocols/protocoldag.py
index 375f3153..85978136 100644
--- a/gufe/protocols/protocoldag.py
+++ b/gufe/protocols/protocoldag.py
@@ -60,7 +60,12 @@ def graph(self) -> nx.DiGraph:
 
     @property
     def protocol_units(self) -> list[ProtocolUnit]:
-        """List of `ProtocolUnit`s given in DAG-dependency order."""
+        """
+        List of `ProtocolUnit`s given in DAG-dependency order.
+
+        DAG-dependency order guarantees that any task is listed after all of its
+        dependencies.
+        """
         return list(self._iterate_dag_order(self._graph))
 
     @property
@@ -154,6 +159,10 @@ def _from_dict(cls, dct: dict):
     def result_graph(self) -> nx.DiGraph:
         """
         DAG of `ProtocolUnitResult` nodes with edges denoting dependencies.
+
+        Each edge is directed from a task towards its dependencies; for example,
+        an edge between a production run and its equilibration would point
+        towards the equilibration unit.
         """
         return self._result_graph
 
@@ -162,7 +171,8 @@ def protocol_unit_results(self) -> list[ProtocolUnitResult]:
         """
         `ProtocolUnitResult`s for each `ProtocolUnit` used to compute this object.
 
-        Results are given in DAG-dependency order.
+        Results are given in DAG-dependency order. In this order, tasks are
+        always listed after their dependencies.
         """
         return list(self._iterate_dag_order(self.result_graph))
 
@@ -172,7 +182,8 @@ def protocol_unit_failures(self) -> list[ProtocolUnitFailure]:
 
         Note
         ----
-        These are returned in DAG order
+        These are returned in DAG order, with tasks listed after their
+        dependencies.
         """
         # mypy can't figure out the types here, .ok() will ensure a certain type
         # https://mypy.readthedocs.io/en/stable/common_issues.html?highlight=cast#complex-type-tests
@@ -184,7 +195,8 @@ def protocol_unit_successes(self) -> list[ProtocolUnitResult]:
 
         Note
         ----
-        These are returned in DAG order
+        These are returned in DAG order, with tasks listed after their
+        dependencies.
         """
         return [r for r in self.protocol_unit_results if r.ok()]
 
@@ -272,7 +284,7 @@ class ProtocolDAG(GufeTokenizable, DAGMixin):
         Optional identifier for this `ProtocolDAGResult`.
     protocol_units : list[ProtocolUnit]
         `ProtocolUnit`s (given in DAG-dependency order) used to compute this
-        `ProtocolDAGResult`.
+        `ProtocolDAGResult`. Tasks are always listed after their dependencies.
     graph : nx.DiGraph
         Graph of `ProtocolUnit`s as nodes, with directed edges to each
         `ProtocolUnit`'s dependencies.