[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 9afeeb4b9adcfd611e1fab816d36042a82216a93..08e61a2c74315dfd1cb2c6ff0ab0beaa1f89b7ff 100644 (file)
--- 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 04071cc3a7f6617ac4fc3aecb5b7b5341af909e8..912804b8c987d75fbb302067fcd3d1007a49ce11 100644 (file)
--- 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