lutaml-model 0.8.99 → 0.8.100

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41d8d37a85f86f8d8f30d632c36526fe311ba0156f01a096a15717627f29ec72
-  data.tar.gz: f15221cd4017756a1045502f77b588df6ae8f3e62ff39b38ac10c8d6f4a68115
+  metadata.gz: 2bd54a574eb02eec487d980543835abb2bec61c12104d6eea6b898a516fb301f
+  data.tar.gz: ffc5d3ed5b0c6df7140839064baec52624a034b2d1c5cfdc764dc4ee78c199ce
 SHA512:
-  metadata.gz: 509fc9f6462f37013113fdcb7a582ca70e9ce0ff021b51c780f9afdd66c03ec2c62213bd0c76a680dc993db138182b7260ed821757b37946b2b61941e2b9b066
-  data.tar.gz: e01bb47f5085c77f6ce840f31ac4f9f243271846267f1083c2c099cfae7f2ced2979f73a61a3a44ea0b0d609b9176a6e8d64e8841994c794382fd0a16c0880f2
+  metadata.gz: 191c5ee654cc6863a6f8d865448f0fbb29c31f7d602e3ab2a356148fdca7117b254aa497bb1ebdd80da1c80f495cf46c5f1029897cf87e7423a7409747e4e97c
+  data.tar.gz: 4b55a05f437df7e0c85c7545d2042990572c70a4d64b42d9ae3ee44950ca6875cd640c2089cd9620951264180556e2e3776e7b32028b1b1d9962cbdaad739ecb

data/docs/_guides/schema-generation.adoc

@@ -901,3 +901,28 @@ The generated schema will include validation constraints:
   </define>
 </grammar>
 ----
+
+== Documentation metadata (desc)
+
+Models and attributes carry documentation strings through `desc` —
+set on the model class or on any `attribute` declaration, read back
+by documentation and schema tooling. Serialization is never affected
+by it.
+
+[source,ruby]
+----
+class Title < Lutaml::Model::Serializable
+  desc "This is a title."
+
+  attribute :type, :string, desc: "This attribute is used for..."
+end
+
+Title.desc # => "This is a title."
+Title.attributes[:type].desc # => "This attribute is used for..."
+----
+
+Subclasses inherit the nearest ancestor's class description; an
+explicit `desc` overrides it. A consumer override-free `desc` value
+does not change any generated schema today — wiring `desc` into the
+generated `description` fields is deliberate product scope, not a
+free rider on this option.

data/lib/lutaml/model/attribute.rb

@@ -46,6 +46,7 @@ module Lutaml
         signed
         min_length
         max_length
+        desc
       ].freeze
 
       # Per-type-class memo of the custom from_xml/from_json probe used by #cast.
@@ -641,6 +642,12 @@ instance_object = nil)
         options[:pattern]
       end
 
+      # Documentation metadata (#356): the `:desc` attribute option,
+      # consumed by documentation and schema tooling.
+      def desc
+        options[:desc]
+      end
+
       # Performance: Frozen empty array to reduce allocations
       EMPTY_VALUES_ARRAY = [].freeze
 

data/lib/lutaml/model/serialize/attribute_definition.rb

@@ -505,6 +505,22 @@ module Lutaml
           end
         end
 
+        # Class-level documentation metadata (#356): `desc "text"` on
+        # the model class; a zero-argument call reads it back.
+        # Subclasses inherit the nearest ancestor's description — an
+        # explicit `desc` overrides. Consumed by documentation and
+        # schema tooling; the serialization paths never read it.
+        def desc(text = nil)
+          return @lutaml_desc = text if text
+
+          return @lutaml_desc if defined?(@lutaml_desc)
+
+          if superclass.is_a?(::Class) &&
+              superclass < ::Lutaml::Model::Serializable
+            superclass.desc
+          end
+        end
+
         # Define an attribute for the model
         #
         # @param name [Symbol] The attribute name

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.99"
+    VERSION = "0.8.100"
   end
 end

data/spec/lutaml/model/desc_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../../spec_helper"
+
+RSpec.describe "Documentation metadata (desc)" do
+  let(:widget_class) do
+    Class.new(Lutaml::Model::Serializable) do
+      desc "A widget."
+
+      attribute :name, :string, desc: "The widget name."
+      attribute :size, :integer
+    end
+  end
+
+  it "stores and reads the class-level description" do
+    expect(widget_class.desc).to eq("A widget.")
+  end
+
+  it "returns nil when no description is set" do
+    plain = Class.new(Lutaml::Model::Serializable)
+    expect(plain.desc).to be_nil
+  end
+
+  it "inherits the description on subclasses" do
+    child = Class.new(widget_class)
+    expect(child.desc).to eq("A widget.")
+  end
+
+  it "lets a subclass override the description" do
+    child = Class.new(widget_class) do
+      desc "A special widget."
+    end
+    expect(child.desc).to eq("A special widget.")
+  end
+
+  it "does not leak an override back to the superclass" do
+    Class.new(widget_class) { desc "Child only." }
+    expect(widget_class.desc).to eq("A widget.")
+  end
+
+  it "stores the attribute-level description" do
+    expect(widget_class.attributes[:name].desc).to eq("The widget name.")
+    expect(widget_class.attributes[:size].desc).to be_nil
+  end
+
+  it "keeps serialization untouched" do
+    widget = widget_class.new(name: "w", size: 3)
+    expect(widget.to_hash).to eq("name" => "w", "size" => 3)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.99
+  version: 0.8.100
 platform: ruby
 authors:
 - Ribose Inc.
@@ -1742,6 +1742,7 @@ files:
 - spec/lutaml/model/deferred_type_no_materialize_spec.rb
 - spec/lutaml/model/delegation_spec.rb
 - spec/lutaml/model/derived_attribute_serialization_spec.rb
+- spec/lutaml/model/desc_spec.rb
 - spec/lutaml/model/dynamic_attribute_spec.rb
 - spec/lutaml/model/encoding_spec.rb
 - spec/lutaml/model/enum_spec.rb