From 1f84108a48a73e27633a7b3c98955cee3237e647 Mon Sep 17 00:00:00 2001
From: toofar <toofar@spalge.com>
Date: Sat, 6 Jan 2024 21:52:53 +1300
Subject: Clarify TraverseOrder Enum values
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I was looking through some commit messages from last week and noticed I
was having trouble keeping track of what these traverse orders meant. So
I tried to adjust the descriptions to be more clear. Hopefully it
worked?

Probably could still use a visual aid though, or the enum value names
could even be changed to be more clear, like "parent-first",
"child-first", "child-first-reverse/-right".

The test I used to verify this description was:

    simple_tree = Node('parent')
    left = Node('left', simple_tree)
    Node('grandleft-left', left)
    Node('grandleft-right', left)
    Node('middle', simple_tree)
    right = Node('right', simple_tree)
    Node('grandright', right)
    # parent
    # ├─ left
    # │ ├─ grandleft-left
    # │ └─ grandleft-right
    # ├─ middle
    # └─ right
    #   └─ grandright

    @pytest.mark.parametrize('order, expected', [
      (TraverseOrder.PRE, "parent left grandleft-left grandleft-right middle right grandright",),
      (TraverseOrder.POST, "grandleft-left grandleft-right left middle grandright right parent",),
      (TraverseOrder.POST_R, "grandright right middle grandleft-right grandleft-left left parent",),
    ])
    def test_simple(order, expected):
        assert expected == " ".join(
            [n.value for n in simple_tree.traverse(order)]
        )
---
 qutebrowser/misc/notree.py | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/qutebrowser/misc/notree.py b/qutebrowser/misc/notree.py
index 78286a6fa..297673bfb 100644
--- a/qutebrowser/misc/notree.py
+++ b/qutebrowser/misc/notree.py
@@ -46,13 +46,15 @@ class TreeError(RuntimeError):
 
 
 class TraverseOrder(enum.Enum):
-    """To be used as argument to traverse().
+    """Tree traversal order for Node.traverse().
+
+    All traversals are depth first.
+    See https://en.wikipedia.org/wiki/Depth-first_search#Vertex_orderings
 
-    Implemented orders are pre-order and post-order.
     Attributes:
-        PRE: pre-order (parents before children). Same as in Node.render
-        POST: children of a node are always yield before their parent.
-        POST_R: Like POST, but children are yield in reverse order
+        PRE: pre-order: parent then children, leftmost nodes first. Same as in Node.render().
+        POST: post-order: children then parent, leftmost nodes first, then parent.
+        POST_R: post-order-reverse: like POST but rightmost nodes first.
     """
 
     PRE = 'pre-order'
-- 
cgit v1.2.3-54-g00ecf