From 4577b459a9043ba283e0d7a39beeddd627cc54a0 Mon Sep 17 00:00:00 2001
From: Ran Benita <ran@unusedvar.com>
Date: Sat, 20 Jan 2024 12:58:24 +0200
Subject: [PATCH] hooks: add comment describing `_hookimpls`'s
 format/invariants.

---
 src/pluggy/_hooks.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/pluggy/_hooks.py b/src/pluggy/_hooks.py
index 916ca704..ed72ed2f 100644
--- a/src/pluggy/_hooks.py
+++ b/src/pluggy/_hooks.py
@@ -389,6 +389,13 @@ def __init__(
         #: Name of the hook getting called.
         self.name: Final = name
         self._hookexec: Final = hook_execute
+        # The hookimpls list. The caller iterates it *in reverse*. Format:
+        # 1. trylast nonwrappers
+        # 2. nonwrappers
+        # 3. tryfirst nonwrappers
+        # 4. trylast wrappers
+        # 5. wrappers
+        # 6. tryfirst wrappers
         self._hookimpls: Final[list[HookImpl]] = []
         self._call_history: _CallHistory | None = None
         # TODO: Document, or make private.