sevgi-graphics 0.93.1 → 0.95.0

data/lib/sevgi/graphics/mixtures/core.rb

@@ -5,9 +5,15 @@ require "forwardable"
 module Sevgi
   module Graphics
     module Mixtures
-      # Internal traversal stop token.
+      # Traversal stop token returned by {Core#Stay}.
+      #
+      # @!attribute [r] value
+      #   @return [Object] value returned from traversal
+      Stop = Data.define(:value)
+
+      # Internal traversal engine.
       # @api private
-      Traversal = Data.define(:value) do
+      module Traversal
         # Runs a depth-first traversal.
         # @param element [Sevgi::Graphics::Element] starting element
         # @param depth [Integer] starting depth
@@ -21,7 +27,7 @@ module Sevgi
         end
 
         def self.stop(value)
-          throw(:traversal, value.value) if value.is_a?(self)
+          throw(:traversal, value.value) if value.is_a?(Stop)
         end
 
         def self.visit(element, depth, leave, &block)
@@ -46,18 +52,17 @@ module Sevgi
         # @param index [Integer] insertion index
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when the target parent has a different element class
+        # @raise [Sevgi::ArgumentError] when the target parent is this element or one of its descendants
+        # @raise [Sevgi::ArgumentError] when index is not an Integer insertion position
         def Adopt(new_parent = nil, index: -1)
           tap do
-            if new_parent
-              unless instance_of?(new_parent.class)
-                ArgumentError.("Element type does not match the new parent type: #{self.class}")
-              end
-            else
-              new_parent = parent
-            end
+            new_parent ||= parent
+            Adoption.validate(self, new_parent)
+
+            insertion = Adoption.index_for(self, new_parent, index)
 
             self.Orphan()
-            (@parent = new_parent).children.insert(index, self)
+            (@parent = new_parent).children.insert(insertion, self)
           end
         end
 
@@ -65,35 +70,38 @@ module Sevgi
         #   Moves this element to the beginning of a parent.
         #   @param new_parent [Sevgi::Graphics::Element, nil] target parent or current parent
         #   @return [Sevgi::Graphics::Element] self
+        #   @raise [Sevgi::ArgumentError] when the target parent has a different element class
+        #   @raise [Sevgi::ArgumentError] when the target parent is this element or one of its descendants
         def AdoptFirst(*)
           Adopt(*, index: 0)
         end
 
-        # Appends existing elements as children.
-        # @param elements [Array<Sevgi::Graphics::Element>] elements to append
+        # Appends distinct existing elements as children in argument order.
+        # Each element transfers from its current parent. The complete batch is validated before any element moves.
+        # @param elements [Array<Sevgi::Graphics::Element>] distinct elements to append
         # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when an argument has a different element class, is repeated, or is this target or its ancestor
         def Append(*elements)
-          tap { elements.each { it.Adopt(self) } }
+          tap { Adoption.batch(elements, self, front: false) }
         end
 
         # Adds CSS classes without duplicating existing values.
-        # @param classes [Array<String, Symbol>] class names
+        # @param classes [Array<String, Symbol, Array>] class tokens; strings are split on whitespace
         # @return [Sevgi::Graphics::Element] self
         def Classify(*classes)
           tap do
-            klasses = case self[:class]
-            when ::Array
-              self[:class]
-            when ::String
-              self[:class].split
-            when nil
-              []
-            else
-              [self[:class]]
+            tokens = proc do |value|
+              case value
+              when nil
+                []
+              when ::Array
+                value.flat_map { tokens.call(it) }
+              else
+                value.to_s.split
+              end
             end
 
-            classes.each { klasses << it unless klasses.include?(it) }
-            self[:class] = klasses
+            self[:class] = [*tokens.call(self[:class]), *tokens.call(classes)].uniq
           end
         end
 
@@ -112,11 +120,14 @@ module Sevgi
 
         # Builds a child element with an explicit tag name.
         # @param tag [Symbol, String] SVG tag name
-        # @param contents [Array<Object>] text or content objects
+        # @param contents [Array<Object>] text or content objects; non-content objects are stringified and XML-encoded
         # @param attributes [Hash] SVG attributes
+        # @yield evaluates the drawing DSL in the new child element
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] new child element
+        # @raise [Sevgi::ArgumentError] when the tag, attributes, or content are not valid XML
         def Element(tag, *contents, **attributes, &block)
-          self.class.send(:new, tag.to_sym, contents: Content.contents(*contents), attributes:, parent: self, &block)
+          self.class.send(:new, tag, contents: Content.contents(*contents), attributes:, parent: self, &block)
         end
 
         # Forwards this element as the first argument to another receiver.
@@ -138,16 +149,18 @@ module Sevgi
         end
 
         # Removes this element from its parent.
-        # @return [Array<Sevgi::Graphics::Element>, nil] parent children after deletion, or nil for root elements
+        # @return [Sevgi::Graphics::Element, nil] the deleted element, or nil for root elements
         def Orphan
           parent.children&.delete(self) unless Root?()
         end
 
-        # Prepends existing elements as children.
-        # @param elements [Array<Sevgi::Graphics::Element>] elements to prepend
+        # Prepends distinct existing elements as children in argument order.
+        # Each element transfers from its current parent. The complete batch is validated before any element moves.
+        # @param elements [Array<Sevgi::Graphics::Element>] distinct elements to prepend
         # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when an argument has a different element class, is repeated, or is this target or its ancestor
         def Prepend(*elements)
-          tap { elements.each { it.AdoptFirst(self) } }
+          tap { Adoption.batch(elements, self, front: true) }
         end
 
         # Returns the root document element.
@@ -168,12 +181,16 @@ module Sevgi
         # @overload Stay(value)
         #   Wraps a traversal return value as a stop token.
         #   @param value [Object] value returned from traversal
-        #   @return [Sevgi::Graphics::Mixtures::Traversal]
-        def Stay(...) = Traversal.new(...)
+        #   @return [Sevgi::Graphics::Mixtures::Stop]
+        def Stay(...) = Stop.new(...)
 
         # Traverses the subtree depth-first.
         # @param depth [Integer] starting depth
         # @param leave [Proc, nil] optional leave callback
+        # @yield [element, depth] visits each element before its children
+        # @yieldparam element [Sevgi::Graphics::Element] visited element
+        # @yieldparam depth [Integer] element depth
+        # @yieldreturn [Object] ignored unless it is a {Stop} token
         # @return [Sevgi::Graphics::Element, Object] self or the value passed through Stay
         # @raise [Sevgi::ArgumentError] when no block is given
         def Traverse(depth = 0, leave = nil, &block)
@@ -184,6 +201,10 @@ module Sevgi
 
         # Traverses ancestors from this element to the root.
         # @param height [Integer] starting height
+        # @yield [element, height] visits this element and each ancestor
+        # @yieldparam element [Sevgi::Graphics::Element] visited element
+        # @yieldparam height [Integer] ancestor height
+        # @yieldreturn [Object] ignored unless it is a {Stop} token
         # @return [Object, nil] value passed through Stay, or nil
         # @raise [Sevgi::ArgumentError] when no block is given
         def TraverseUp(height = 0, &block)
@@ -192,7 +213,7 @@ module Sevgi
           element = self
 
           loop do
-            yield(element, height).tap { return it.value if it.is_a?(Traversal) }
+            yield(element, height).tap { return it.value if it.is_a?(Stop) }
 
             break if element.Root?()
 
@@ -204,6 +225,8 @@ module Sevgi
         # Evaluates a block in the parent element context.
         # @param args [Array<Object>] optional receiver override followed by block arguments
         # @param kwargs [Hash] keyword arguments passed to the block
+        # @yield evaluates in the selected receiver's parent context
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         def With(*args, **kwargs, &block)
           tap { (args.shift || self).parent.instance_exec(*args, **kwargs, &block) }
@@ -212,6 +235,8 @@ module Sevgi
         # Evaluates a block in this element context.
         # @param args [Array<Object>] optional receiver override followed by block arguments
         # @param kwargs [Hash] keyword arguments passed to the block
+        # @yield evaluates in the selected receiver context
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         def Within(*args, **kwargs, &block)
           tap { (args.shift || self).instance_exec(*args, **kwargs, &block) }
@@ -223,6 +248,84 @@ module Sevgi
         def <<(element)
           Append(element)
         end
+
+        # Adoption target validation that keeps tree mutation atomic.
+        # @api private
+        module Adoption
+          # Moves a validated batch to the front or back of a parent.
+          # @param elements [Array<Sevgi::Graphics::Element>] elements to move
+          # @param parent [Sevgi::Graphics::Element] target parent
+          # @param front [Boolean] whether to prepend instead of append
+          # @return [void]
+          # @raise [Sevgi::ArgumentError] when an argument is incompatible, repeated, or would create a cycle
+          def self.batch(elements, parent, front:)
+            validate_batch(elements, parent)
+
+            if front
+              elements.reverse_each { it.AdoptFirst(parent) }
+            else
+              elements.each { it.Adopt(parent) }
+            end
+          end
+
+          # Rejects target parents that would create a cycle.
+          # @param element [Sevgi::Graphics::Element] element being moved
+          # @param parent [Sevgi::Graphics::Element, Object] target parent
+          # @return [void]
+          # @raise [Sevgi::ArgumentError] when the parent is incompatible or would create a cycle
+          def self.validate(element, parent)
+            unless element.instance_of?(parent.class)
+              ArgumentError.("Element type does not match the new parent type: #{element.class}")
+            end
+
+            ArgumentError.("Element cannot be adopted under itself") if parent.equal?(element)
+
+            while parent.respond_to?(:Root?)
+              ArgumentError.("Element cannot be adopted under its descendant") if parent.equal?(element)
+              break if parent.Root?()
+
+              parent = parent.parent
+            end
+          end
+
+          # Normalizes an insertion index before tree mutation.
+          # @param index [Integer] requested insertion index
+          # @param size [Integer] number of available child positions
+          # @return [Integer] normalized non-negative insertion index
+          # @raise [Sevgi::ArgumentError] when the index is not an insertion position
+          def self.index(index, size)
+            ArgumentError.("Adoption index must be an Integer") unless index.is_a?(Integer)
+
+            normalized = index.negative? ? size + index + 1 : index
+            ArgumentError.("Adoption index is outside the child list") unless normalized.between?(0, size)
+
+            normalized
+          end
+
+          # Returns an insertion index after accounting for a same-parent move.
+          # @param element [Sevgi::Graphics::Element] element being moved
+          # @param parent [Sevgi::Graphics::Element] target parent
+          # @param index [Integer] requested insertion index
+          # @return [Integer] normalized insertion index
+          def self.index_for(element, parent, index)
+            same_parent = element.parent.equal?(parent) && parent.children.include?(element)
+            index(index, parent.children.size - (same_parent ? 1 : 0))
+          end
+
+          def self.validate_batch(elements, parent)
+            seen = {}.compare_by_identity
+            elements.each do |element|
+              ArgumentError.("Element appears more than once in adoption batch") if seen.key?(element)
+
+              seen[element] = true
+              validate(element, parent)
+            end
+          end
+
+          private_class_method :validate_batch
+        end
+
+        private_constant :Adoption
       end
     end
   end

data/lib/sevgi/graphics/mixtures/duplicate.rb

@@ -3,41 +3,91 @@
 module Sevgi
   module Graphics
     module Mixtures
-      # DSL helpers for duplicating elements and their subtrees.
+      # DSL helpers for duplicating independent element subtrees.
       module Duplicate
-        # Duplicates an element subtree and optionally translates it.
+        # Duplicates an element subtree as an independent tree and optionally translates it.
+        # Copied elements receive new child arrays, attribute stores, and content arrays. Public `id` attributes are
+        # moved to an internal `-id` attribute before the optional block runs, allowing the block to derive replacement
+        # ids without rendering duplicate public ids.
         # @param dx [Numeric, nil] x translation
         # @param dy [Numeric, nil] y translation
         # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
+        # @yield [element] optional customization hook for each copied element
+        # @yieldparam element [Sevgi::Graphics::Element] copied element
+        # @yieldreturn [Object] ignored customization result
         # @return [Sevgi::Graphics::Element] duplicated element
+        # @raise [Sevgi::ArgumentError] when the target parent has a different element class
+        # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
         def Duplicate(dx: nil, dy: nil, parent: nil, &block)
-          duplicated = dup
-
-          duplicated.Traverse() do |element|
-            element.children = element.children.map(&:dup)
-            id = (element.attributes = element.attributes.dup).delete(:id)
-            element[:"#{ATTRIBUTE_INTERNAL_PREFIX}id"] = id if id
-            block&.call(element)
-          end
-
-          duplicated.Translate(dx, dy) if dx || dy
-
-          duplicated.Adopt(parent)
-
-          duplicated
+          duplicated = Subtree.copy(self)
+          Subtree.prepare(duplicated, &block)
+          Subtree.translate(duplicated, dx, dy)
+          Subtree.attach(duplicated, self, parent)
         end
 
         # Duplicates an element subtree along the x-axis.
         # @param dx [Numeric] x translation
         # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
+        # @yield [element] optional customization hook for each copied element
+        # @yieldparam element [Sevgi::Graphics::Element] copied element
+        # @yieldreturn [Object] ignored customization result
         # @return [Sevgi::Graphics::Element] duplicated element
+        # @raise [Sevgi::ArgumentError] when the target parent has a different element class
+        # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
         def DuplicateX(dx, parent: nil, &block) = Duplicate(dx:, dy: 0, parent:, &block)
 
         # Duplicates an element subtree along the y-axis.
         # @param dy [Numeric] y translation
         # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
+        # @yield [element] optional customization hook for each copied element
+        # @yieldparam element [Sevgi::Graphics::Element] copied element
+        # @yieldreturn [Object] ignored customization result
         # @return [Sevgi::Graphics::Element] duplicated element
+        # @raise [Sevgi::ArgumentError] when the target parent has a different element class
+        # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
         def DuplicateY(dy, parent: nil, &block) = Duplicate(dx: 0, dy:, parent:, &block)
+
+        # Recursive subtree copier that keeps duplicate implementation state out of the DSL surface.
+        # @api private
+        module Subtree
+          # Builds an independent copy of an element subtree.
+          # @param element [Sevgi::Graphics::Element] source subtree root
+          # @param parent [Sevgi::Graphics::Element, Object] parent for the copied root
+          # @return [Sevgi::Graphics::Element] copied subtree root
+          def self.copy(element, parent = element.parent)
+            element.dup.tap do |duplicated|
+              duplicated.send(:parent=, parent)
+              duplicated.send(:attributes=, element.attributes.dup)
+              duplicated.send(:contents=, element.contents.map(&:dup))
+              duplicated.send(:children=, element.children.map { |child| copy(child, duplicated) })
+            end
+          end
+
+          # Removes copied public ids and applies an optional customization hook.
+          # @api private
+          def self.prepare(element, &block)
+            element.Traverse() do |node|
+              id = node.attributes.delete(:id)
+              node[:"#{ATTRIBUTE_INTERNAL_PREFIX}id"] = id if id
+              block&.call(node)
+            end
+          end
+
+          # Applies an optional translation to a copied subtree.
+          # @api private
+          def self.translate(element, dx, dy)
+            element.Translate(dx, dy) if dx || dy
+          end
+
+          # Attaches a copied subtree unless it is a detached root copy.
+          # @api private
+          def self.attach(element, source, parent)
+            element.Adopt(parent) if parent || !source.Root?()
+            element
+          end
+        end
+
+        private_constant :Subtree
       end
     end
   end

data/lib/sevgi/graphics/mixtures/export.rb

@@ -8,9 +8,13 @@ module Sevgi
         # Exports the document as PDF.
         # @param path [String, nil] output path or directory
         # @param kwargs [Hash] export options
+        # @yield [svg] transforms SVG source before rendering
+        # @yieldparam svg [String] rendered SVG source
+        # @yieldreturn [String] transformed SVG source
         # @return [String] output path
         # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
-        # @raise [Sevgi::Sundries::ExportError] when native export fails
+        # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
+        # @raise [Sevgi::Sundries::Export::ExportError] when native export fails
         def PDF(path = nil, **kwargs, &block)
           begin
             require "sevgi/sundries"
@@ -27,9 +31,13 @@ module Sevgi
         # Exports the document as PNG.
         # @param path [String, nil] output path or directory
         # @param kwargs [Hash] export options
+        # @yield [svg] transforms SVG source before rendering
+        # @yieldparam svg [String] rendered SVG source
+        # @yieldreturn [String] transformed SVG source
         # @return [String] output path
         # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
-        # @raise [Sevgi::Sundries::ExportError] when native export fails
+        # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
+        # @raise [Sevgi::Sundries::Export::ExportError] when native export fails
         def PNG(path = nil, **kwargs, &block)
           begin
             require "sevgi/sundries"

data/lib/sevgi/graphics/mixtures/identify.rb

@@ -45,7 +45,9 @@ module Sevgi
 
           def build
             element.Traverse() do |element|
-              next unless (id = element[:id])
+              next unless (value = element[:id])
+
+              id = Attribute.xml_text(value)
 
               if @namespace.key?(id)
                 (@collision[id] ||= [@namespace[id]]) << element

data/lib/sevgi/graphics/mixtures/include.rb

@@ -4,22 +4,48 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for including derendered SVG/XML fragments.
+      #
+      # @!method Include(file, id)
+      #   Includes a derendered node matching an id.
+      #   SVG/XML content is treated as data and is not evaluated as Ruby source.
+      #   @param file [String] source SVG/XML file
+      #   @param id [String, Symbol] source node id
+      #   @return [Sevgi::Graphics::Element, nil] included element, or nil when it produces no graphics output
+      #   @raise [Sevgi::ArgumentError] when the file is absent or XML content is malformed, rootless, or lacks the id
+      #   @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
+      # @!method IncludeChildren(file, id)
+      #   Includes the children of a derendered node matching an id.
+      #   SVG/XML content is treated as data and is not evaluated as Ruby source.
+      #   @param file [String] source SVG/XML file
+      #   @param id [String, Symbol] source node id
+      #   @return [Array<Sevgi::Graphics::Element>] included children
+      #   @raise [Sevgi::ArgumentError] when the file is absent or XML content is malformed, rootless, or lacks the id
+      #   @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
       module Include
         require "sevgi/derender"
 
         # Includes a derendered node matching an id.
+        #
+        # SVG/XML file content is treated as data and is not evaluated as Ruby source.
         # @param file [String] source SVG/XML file
         # @param id [String, Symbol] source node id
-        # @return [Sevgi::Graphics::Element] included element
+        # @return [Sevgi::Graphics::Element, nil] included element, or nil when the selected node produces no graphics
+        #   output
+        # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+        #   absent
         # @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
         def Include(file, id) = Derender.evaluate_file(file, self, id:)
 
         # Includes the children of a derendered node matching an id.
+        #
+        # SVG/XML file content is treated as data and is not evaluated as Ruby source.
         # @param file [String] source SVG/XML file
         # @param id [String, Symbol] source node id
         # @return [Array<Sevgi::Graphics::Element>] included children
+        # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+        #   absent
         # @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
-        def IncludeChildren(file, id) = Derender.evaluate_file!(file, self, id:)
+        def IncludeChildren(file, id) = Derender.evaluate_file_children(file, self, id:)
       rescue ::LoadError => e
         raise unless e.path == "sevgi/derender"
 

data/lib/sevgi/graphics/mixtures/inkscape.rb

@@ -26,6 +26,8 @@ module Sevgi
         # @param mod [Module] callable drawing module
         # @param args [Array<Object>] callable arguments
         # @param kwargs [Hash] group attributes
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] group element
         # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Group(mod, *args, **kwargs, &block)
@@ -37,6 +39,8 @@ module Sevgi
         # @param mod [Module] callable drawing module
         # @param args [Array<Object>] callable arguments
         # @param kwargs [Hash] layer attributes
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] layer element
         # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Layer(mod, *args, **kwargs, &block)
@@ -48,6 +52,8 @@ module Sevgi
         # @param mod [Module] callable drawing module
         # @param args [Array<Object>] callable arguments
         # @param kwargs [Hash] layer attributes
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] layer element
         # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Layer!(mod, *args, **kwargs, &block)
@@ -58,6 +64,8 @@ module Sevgi
         # @overload layer(**attributes)
         #   Builds an Inkscape layer group.
         #   @param attributes [Hash] layer attributes
+        #   @yield evaluates the drawing DSL in the layer
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] layer group
         def layer(**, &block)
           g("inkscape:groupmode": "layer", **, &block)
@@ -66,6 +74,8 @@ module Sevgi
         # @overload layer!(**attributes)
         #   Builds an insensitive Inkscape layer group.
         #   @param attributes [Hash] layer attributes
+        #   @yield evaluates the drawing DSL in the layer
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] layer group
         def layer!(**, &block)
           layer("sodipodi:insensitive": "true", **, &block)
@@ -74,6 +84,9 @@ module Sevgi
         # Builds an Inkscape namedview containing page elements.
         # @param pages [Array<Hash>] page attribute hashes
         # @param id [String] namedview id
+        # @yield [page] customizes each generated page element
+        # @yieldparam page [Sevgi::Graphics::Element] generated page element
+        # @yieldreturn [Object] ignored customization result
         # @return [Sevgi::Graphics::Element] namedview element
         def Pages(*pages, id: "namedview", **, &block)
           Element(:"sodipodi:namedview", id:, **) do
@@ -111,6 +124,8 @@ module Sevgi
         # @overload symbol!(**attributes)
         #   Builds an Inkscape symbol group hidden from the symbols menu.
         #   @param attributes [Hash] symbol attributes
+        #   @yield evaluates the drawing DSL in the symbol group
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] symbol group
         def symbol!(**, &block)
           if Is?(:defs)

data/lib/sevgi/graphics/mixtures/rdf.rb

@@ -7,6 +7,8 @@ module Sevgi
       module RDF
         # Adds RDF license metadata inside a metadata element.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License(**kwargs, &block) = metadata { RDFWork(**kwargs, &block) }
 
@@ -14,6 +16,8 @@ module Sevgi
         #
         # Adds Creative Commons BY-SA license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_SA(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-sa/4.0/", &block)
@@ -21,6 +25,8 @@ module Sevgi
 
         # Adds Creative Commons BY-NC license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc/4.0/", &block)
@@ -28,6 +34,8 @@ module Sevgi
 
         # Adds Creative Commons BY-NC-SA license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC_SA(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc-sa/4.0/", &block)
@@ -35,6 +43,8 @@ module Sevgi
 
         # Adds Creative Commons BY-ND license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_ND(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nd/4.0/", &block)
@@ -42,6 +52,8 @@ module Sevgi
 
         # Adds Creative Commons BY-NC-ND license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC_ND(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc-nd/4.0/", &block)
@@ -49,6 +61,8 @@ module Sevgi
 
         # Adds Creative Commons Zero metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC0(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/publicdomain/zero/1.0/", &block)
@@ -56,11 +70,15 @@ module Sevgi
 
         # Adds Free Art License metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_LAL(**kwargs, &block) = License(**kwargs, license: "https://artlibre.org/licence/lal/en/", &block)
 
         # Builds an RDF root element.
         # @param _kwargs [Hash] currently unused options
+        # @yield evaluates the RDF drawing DSL
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] RDF element
         # @raise [Sevgi::ArgumentError] when no block is given
         def RDF(**_kwargs, &block)
@@ -86,6 +104,8 @@ module Sevgi
         # @option kwargs [String] :date date
         # @option kwargs [String] :language language
         # @option kwargs [String] :license license URL
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] RDF element
         def RDFWork(**kwargs, &block)
           RDF do