From 8309f0a9d842c6fcb277c3f869c5811736312db9 Mon Sep 17 00:00:00 2001
From: Eric Lau <ericglau@outlook.com>
Date: Fri, 23 Oct 2026 14:10:41 -0400
Subject: [PATCH] Document rename and retype annotations on struct members

---
 content/upgrades-plugins/faq.mdx | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/content/upgrades-plugins/faq.mdx b/content/upgrades-plugins/faq.mdx
index d92e2d7f..b0367032 100644
--- a/content/upgrades-plugins/faq.mdx
+++ b/content/upgrades-plugins/faq.mdx
@@ -223,7 +223,34 @@ contract V2 {
 }
 ```
 
-Docstring comments don’t yet work for struct members, due to a current Solidity limitation.
+Since `@openzeppelin/upgrades-core@1.47.0`, these docstring comments can also be used on struct members, including members of [namespaced storage](/upgrades-plugins/writing-upgradeable#namespaced-storage-layout) structs, for example:
+
+```solidity
+contract V1 {
+    /// @custom:storage-location erc7201:example.main
+    struct MainStorage {
+        uint x;
+        bool f;
+    }
+
+    ...
+}
+contract V2 {
+    /// @custom:storage-location erc7201:example.main
+    struct MainStorage {
+        /// @custom:oz-renamed-from x
+        uint y;
+        /// @custom:oz-retyped-from bool
+        uint8 f;
+    }
+
+    ...
+}
+```
+
+<Callout>
+When validating with the [OpenZeppelin Upgrades CLI](/upgrades-plugins/api-core), which [Foundry Upgrades](/upgrades-plugins/foundry/foundry-upgrades) also uses, the storage slots of namespaced struct members are not available. As a result, a `@custom:oz-retyped-from` annotation on a namespaced struct member is only accepted for type changes known to keep the same layout, such as between `bool` and `uint8`.
+</Callout>
 
 ## How can I use internal functions in storage variables?