From: Vsevolod Stakhov <vsevolod@rspamd.com>
Date: Thu, 25 Dec 2025 15:24:19 +0000 (+0000)
Subject: [Fix] Preserve doc from optional wrappers in lua_shape
X-Git-Tag: 3.14.3~28
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=38edf25a7d66fec3f493d6beb0824c4e91655b59;p=thirdparty%2Frspamd.git

[Fix] Preserve doc from optional wrappers in lua_shape

When a schema field uses :optional():doc(), the documentation was lost
during table field normalization. Now propagates doc to inner schema.
---

diff --git a/lualib/lua_shape/core.lua b/lualib/lua_shape/core.lua
index 9afeeb4b9a..08e61a2c74 100644
--- a/lualib/lua_shape/core.lua
+++ b/lualib/lua_shape/core.lua
@@ -565,8 +565,18 @@ function T.table(fields, opts)
       local inner_schema = is_optional and val.inner or val
       local default_value = is_optional and val.default or nil
 
+      -- Propagate doc from optional wrapper to inner schema
+      local schema_to_store = inner_schema
+      if is_optional and val.opts and val.opts.doc then
+        schema_to_store = shallowcopy(inner_schema)
+        local new_opts = shallowcopy(inner_schema.opts or {})
+        new_opts.doc = val.opts.doc
+        schema_to_store.opts = new_opts
+        setmetatable(schema_to_store, getmetatable(inner_schema))
+      end
+
       normalized_fields[key] = {
-        schema = inner_schema,
+        schema = schema_to_store,
         optional = is_optional,
         default = default_value
       }
diff --git a/lualib/lua_shape/docs.lua b/lualib/lua_shape/docs.lua
index 04071cc3a7..912804b8c9 100644
--- a/lualib/lua_shape/docs.lua
+++ b/lualib/lua_shape/docs.lua
@@ -143,6 +143,17 @@ local function generate_doc_impl(schema, path)
     if schema.default ~= nil then
       result.default = schema.default
     end
+    -- Preserve doc from optional wrapper
+    local wrapper_doc = get_doc(schema.opts)
+    if wrapper_doc.summary and not result.summary then
+      result.summary = wrapper_doc.summary
+    end
+    if wrapper_doc.description and not result.description then
+      result.description = wrapper_doc.description
+    end
+    if wrapper_doc.examples and not result.examples then
+      result.examples = wrapper_doc.examples
+    end
 
   -- Transform wrapper
   elseif tag == "transform" then