From 4438c5807d05d20bff51dd637ea30688ed5f9ad5 Mon Sep 17 00:00:00 2001
From: tianfenghan <rango@swoole.com>
Date: Fri, 28 Aug 2026 17:27:56 +0800
Subject: [PATCH] docs: clarify attribute factory name resolution timing

---
 src/Transform/RuntimeAttributeFactoryLowering.php | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/Transform/RuntimeAttributeFactoryLowering.php b/src/Transform/RuntimeAttributeFactoryLowering.php
index 0a884da2..11bd393e 100644
--- a/src/Transform/RuntimeAttributeFactoryLowering.php
+++ b/src/Transform/RuntimeAttributeFactoryLowering.php
@@ -278,9 +278,11 @@ final class RuntimeAttributeFactoryLowering extends NodeVisitorAbstract
                     }
                 }
                 if ($node instanceof Node\Name) {
-                    // Attribute factories are created while the outer
-                    // traverser is entering the Attribute node, before its
-                    // argument names have been visited by NameResolver.
+                    // Attribute factories are created in leaveNode(), after
+                    // their argument names have passed through NameResolver.
+                    // The compiler keeps the original node and records its
+                    // target in resolvedName, while the stub pipeline may
+                    // replace it with a FullyQualified node directly.
                     if ($node instanceof Node\Name\Relative) {
                         $name = ltrim($this->namespace . '\\' . $node->toString(), '\\');
                         return new Node\Name\FullyQualified($name, $node->getAttributes());