ynl 0.3.0 → 0.4.2

data/lib/ynl/generator.rb

@@ -1,5 +1,7 @@
 module Ynl
+  # Generates Ruby code from a parsed YNL specification.
   class Generator
+    # @private
     module Refinements
       WORD_DELIM = /[ _-]+/
 
@@ -32,7 +34,6 @@ module Ynl
 
     PRELUDE = -<<~RUBY
       # frozen_string_literal: true
-      # rbs_inline: enabled
       # This code is generated by Ynl::Generator. DO NOT EDIT.
       require 'nl'
     RUBY
@@ -41,16 +42,22 @@ module Ynl
       'admin-perm' => 'Requires CAP_NET_ADMIN in the initial user namespace.',
       'uns-admin-perm' => 'Requires CAP_NET_ADMIN in the user namespace owning the network namespace.',
     }.freeze
-    private_constant :OPERATION_FLAG_DOCS
+    KERNEL_DOC_REFERENCE = %r{Documentation/(?<path>[A-Za-z0-9_./+-]+)\.rst\b}
+    private_constant :OPERATION_FLAG_DOCS, :KERNEL_DOC_REFERENCE
 
+    # @rbs (Models::Family ynl, _Writable out) -> void
     def initialize(ynl, out)
       @ynl = ynl
       @out = out
       @indent = 0
     end
 
-    def generate(superclass: '::Nl::Family', namespace: nil)
-      @protocol = '::Nl::Protocols::' + (@ynl.protocol == 'netlink-raw' ? 'Raw' : 'Genl')
+    # @rbs (?superclass: String?, ?namespace: String?, ?default_resolver: String?) -> void
+    def generate(superclass: nil, namespace: nil, default_resolver: nil)
+      raw = @ynl.protocol == 'netlink-raw'
+      @wire = raw ? '::Nl::Raw' : '::Nl::Genl'
+      superclass ||= raw ? '::Nl::Raw::Family' : '::Nl::Genl::Family'
+      build_selector_plan
 
       emit_comment(@ynl.doc)
 
@@ -58,37 +65,62 @@ module Ynl
       emit_class([*namespace, classname].join('::'), superclass) do
         emit_const('NAME', @ynl.name.as_string_literal)
 
-        if @ynl.protocol == 'netlink-raw'
-          emit_const('PROTOCOL', "Ractor.make_shareable(::Nl::Protocols::Raw.new(#{@ynl.name.as_string_literal}, #{@ynl.protonum}))")
-        else
-          emit_const('PROTOCOL', "Ractor.make_shareable(::Nl::Protocols::Genl.new(#{@ynl.name.as_string_literal}))")
-        end
+        emit_const('PROTONUM', @ynl.protonum) if raw
+        emit_const('VERSION', @ynl.version) unless raw
+        emit_open(raw:, default_resolver:, classname:)
 
         emit_mcast_groups
 
+        unless @ynl.consts.empty?
+          emit_module('Constants') do
+            @ynl.consts.each_value do |const|
+              emit_comment(const.doc)
+              emit_const(const.name.as_const_name, const_value_literal(const.value))
+            end
+          end
+        end
+
+        emit_value_definitions('Enums', @ynl.enums.values) { |_definition, entry| entry.value }
+        emit_value_definitions('Flags', @ynl.flags.values + enums_used_as_flags) do |definition, entry|
+          definition.is_a?(Models::Enum) ? 1 << entry.value : entry.value
+        end
+
+        deferred_struct_consts = []
         emit_module('Structs') do
           @ynl.structs.each do |name, struct|
             emit_comment(struct.doc)
             write(name.as_class_name, " = Struct.new(")
             indent do
               struct.members.each do |member|
-                write(member.name.as_variable_name.as_symbol_literal, ', #: ', member.type.rbs_type)
+                write(member.name.as_variable_name.as_symbol_literal, ', #: ', struct_member_rbs_type(member.type))
               end
             end
             write(')')
             emit_class(name.as_class_name) do
-              emit_nodoc
-              emit_const(
-                'MEMBERS',
-                "Ractor.make_shareable({#{struct.members.map { "#{it.name.as_variable_name}: #{to_datatype(it.type, nil)}" }.join(', ') }})",
-                rbs: 'Hash[::Symbol, ::Nl::_DataType]',
-              )
+              struct.members.each do |member|
+                emit_yard_attribute(
+                  member.name.as_method_name,
+                  struct_member_yard_type(member.type),
+                  member.doc,
+                )
+              end
+              members = struct.members.map do |member|
+                "#{member.name.as_variable_name}: #{to_struct_member_datatype(member.type)}"
+              end
+              members = "Ractor.make_shareable({#{members.join(', ')}})"
+              if struct.members.any? { it.type.is_a?(Types::Binary) && it.type.struct }
+                deferred_struct_consts << ["Structs::#{name.as_class_name}::MEMBERS", members]
+              else
+                emit_const('MEMBERS', members, rbs: 'Hash[::Symbol, ::Nl::_DataType]', internal: true)
+              end
 
               emit_comment('Decodes the struct.')
               emit_rbs_comment(
                 'decoder: ::Nl::Decoder',
                 'return: instance',
               )
+              emit_yard_param('decoder', 'Nl::Decoder')
+              emit_yard_return('self')
               write('def self.decode(decoder)')
               indent do
                 write('self.new(*MEMBERS.map {|name, datatype| datatype.decode(decoder) })')
@@ -100,6 +132,8 @@ module Ynl
                 'encoder: ::Nl::Encoder',
                 'return: void',
               )
+              emit_yard_param('encoder', 'Nl::Encoder')
+              emit_yard_return('void')
               write('def encode(encoder)')
               indent do
                 write('MEMBERS.each {|name, datatype| datatype.encode(encoder, self.public_send(name)) }')
@@ -108,50 +142,91 @@ module Ynl
             end
           end
         end
+        deferred_struct_consts.each do |name, members|
+          emit_const(name, members, rbs: 'Hash[::Symbol, ::Nl::_DataType]', internal: true)
+        end
 
+        deferred_sub_message_datatypes = []
         emit_module('AttributeSets') do
           deferred_consts = []
           @ynl.attribute_sets.each do |name, attr_set|
             emit_comment(attr_set.doc)
-            emit_class(name.as_class_name, @protocol + '::AttributeSet') do
+            emit_class(name.as_class_name, '::Nl::AttributeSet') do
               emit_comment("Abstract class")
-              emit_class('Attribute', @protocol + '::AttributeSet::Attribute') do
+              emit_class('Attribute', '::Nl::AttributeSet::Attribute') do
               end
               attr_set.attributes.each do |attr|
-                emit_comment(attr.doc)
+                emit_comment(attribute_doc(attr))
                 emit_class(attr.name.as_class_name, 'Attribute') do
                   emit_const('TYPE', attr.value)
                   emit_const('NAME', attr.name.as_variable_name.as_symbol_literal)
-                  if attr.type.is_a?(Types::NestedAttributes) ||
+                  emit_const('MULTI', 'true', internal: true) if attr.multi?
+                  emit_const('ORDER', @attribute_orders.fetch(attr_set).fetch(attr), internal: true)
+                  if slot = @local_selectors.fetch(attr_set).index(attr.name)
+                    emit_const('SELECTOR_SLOT', slot, internal: true)
+                  end
+                  if attr.type.is_a?(Types::SubMessage)
+                    deferred_sub_message_datatypes << [
+                      "AttributeSets::#{name.as_class_name}::#{attr.name.as_class_name}::DATATYPE",
+                      to_datatype(attr.type, attr.checks, owner: attr_set),
+                    ]
+                  elsif attr.type.is_a?(Types::NestedAttributes) ||
                     attr.type.is_a?(Types::NestTypeValue) ||
                     (attr.type.is_a?(Types::IndexedArray) && attr.type.sub_type.is_a?(Types::NestedAttributes))
-                    deferred_consts << ["#{name.as_class_name}::#{attr.name.as_class_name}::DATATYPE", to_datatype(attr.type, attr.checks)]
+                    deferred_consts << ["#{name.as_class_name}::#{attr.name.as_class_name}::DATATYPE", to_datatype(attr.type, attr.checks, owner: attr_set)]
                   else
-                    emit_const('DATATYPE', to_datatype(attr.type, attr.checks))
+                    emit_const('DATATYPE', to_datatype(attr.type, attr.checks, owner: attr_set), internal: true)
                   end
                 end
               end
 
-              emit_nodoc
+              selector_names = @local_selectors.fetch(attr_set)
+              external_selector_names = @external_selectors.fetch(attr_set)
+              unless selector_names.empty? && external_selector_names.empty?
+                emit_const(
+                  'SELECTOR_NAMES',
+                  "Ractor.make_shareable({local: [#{selector_names.map { it.as_variable_name.as_symbol_literal }.join(', ')}], external: [#{external_selector_names.map { it.as_variable_name.as_symbol_literal }.join(', ')}]})",
+                  internal: true,
+                )
+              end
+
               emit_const(
                 'BY_NAME',
                 "Ractor.make_shareable({#{attr_set.attributes.map { "#{it.name.as_variable_name.as_symbol_literal} => #{it.name.as_class_name}" }.join(', ') }})",
                 rbs: 'Hash[::Symbol, Attribute]',
+                internal: true,
               )
 
-              emit_nodoc
               emit_const(
                 'BY_TYPE',
                 "Ractor.make_shareable({#{attr_set.attributes.map { "#{it.value} => #{it.name.as_class_name}" }.join(', ') }})",
                 rbs: 'Hash[::Integer, Attribute]',
+                internal: true,
               )
 
+              attr_set.attributes.each do |attribute|
+                next if attribute.type.is_a?(Types::Pad)
+
+                emit_comment(attribute_doc(attribute))
+                emit_rbs_comment('return: ' + attribute_rbs_type(attribute))
+                emit_yard_return(attribute_yard_type(attribute))
+                emit_yard_see(attribute.name.as_class_name)
+                expression = if attribute.multi?
+                  "self[#{attribute.name.as_variable_name.as_symbol_literal}].map(&:value)"
+                else
+                  "self[#{attribute.name.as_variable_name.as_symbol_literal}]&.value"
+                end
+                emit_getter(attribute.name.as_method_name, expression)
+              end
+
               emit_singleton_class do
                 emit_comment('Looks up Attribute class by name.')
                 emit_rbs_comment(
                   'name: Symbol',
                   'return: Attribute',
                 )
+                emit_yard_param('name', 'Symbol')
+                emit_yard_return('Attribute')
                 emit_getter('by_name(name)', 'BY_NAME.fetch(name)')
 
                 emit_comment('Looks up Attribute class by type value.')
@@ -159,11 +234,21 @@ module Ynl
                   'type: Integer',
                   'return: Attribute',
                 )
+                emit_yard_param('type', 'Integer')
+                emit_yard_return('Attribute')
                 emit_getter('by_type(type)', 'BY_TYPE.fetch(type)')
               end
             end
           end
-          deferred_consts.each { emit_const(*it) }
+          deferred_consts.each do |const|
+            emit_const(*const, internal: true)
+          end
+        end
+
+
+        emit_sub_messages
+        deferred_sub_message_datatypes.each do |const|
+          emit_const(*const, internal: true)
         end
 
         emit_module('Messages') do
@@ -201,6 +286,7 @@ module Ynl
           'NOTIFICATIONS',
           "Ractor.make_shareable({#{notification_operations.map { |oper| "#{oper.notification.message.value} => Notifications::#{oper.name.as_class_name}" }.join(', ') }})",
           rbs: 'Hash[::Integer, ::Class]',
+          internal: true,
         )
 
         # emit request methods
@@ -218,15 +304,28 @@ module Ynl
               params = header_params + attribute_params
               params.reject! { it.type.is_a? Types::Pad }
 
-              rbs_params = params.map { |it| "?#{it.name.as_variable_name}: #{it.type.rbs_type}" }.join(', ')
+              rbs_params = params.map { |it| "?#{it.name.as_variable_name}: #{parameter_rbs_type(it)}" }.join(', ')
               rbs_result = request_reply.reply ? reply_class : 'void'
 
               emit_comment(operation_doc(oper))
               if method == 'dump'
+                method_name = "#{method.as_method_name}_#{oper.name.as_method_name}"
                 emit_rbs_comment(
-                  "(#{rbs_params}) -> Enumerable[#{rbs_result}]\n  | (#{rbs_params}) { (#{rbs_result}) -> void } -> void",
+                  "(#{rbs_params}) -> Array[#{rbs_result}]\n  | (#{rbs_params}) { (#{rbs_result}) -> void } -> void",
                 )
-                write("def #{method.as_method_name}_#{oper.name.as_method_name}(**args, &block)")
+                emit_yard_overload("#{method_name}(**args)") do |indentation|
+                  emit_comment("#{indentation}Returns an array when no block is given.")
+                  emit_yard_options(params, indentation:)
+                  emit_yard_return("Array<#{rbs_result}>", indentation:)
+                end
+                emit_yard_overload("#{method_name}(**args, &block)") do |indentation|
+                  emit_comment("#{indentation}Yields each reply when a block is given.")
+                  emit_yard_options(params, indentation:)
+                  emit_yard_yieldparam('reply', rbs_result, indentation:)
+                  emit_yard_return('void', indentation:)
+                end
+                emit_yard_see(request_class)
+                write("def #{method_name}(**args, &block)")
                 indent do
                   write("exchange_message(#{method.as_symbol_literal}, #{request_class}, #{reply_class}, args, &block)")
                 end
@@ -234,6 +333,9 @@ module Ynl
                 emit_rbs_comment(
                   "(#{rbs_params}) -> #{rbs_result}",
                 )
+                emit_yard_options(params)
+                emit_yard_return(rbs_result)
+                emit_yard_see(request_class)
                 write("def #{method.as_method_name}_#{oper.name.as_method_name}(**args)")
                 indent do
                   write("exchange_message(#{method.as_symbol_literal}, #{request_class}, #{reply_class}, args)")
@@ -245,7 +347,7 @@ module Ynl
         end
 
         emit_class('AsyncOperations') do
-          emit_nodoc
+          emit_internal
           write('def initialize(&exchange)')
           indent do
             write('@exchange = exchange')
@@ -262,12 +364,16 @@ module Ynl
               attribute_params = oper.attribute_set.attributes.filter { request_reply.request.attributes.include?(it.name) }
               attribute_params.reject! {|a| header_params.any? {|h| h.name == a.name } }
               params = (header_params + attribute_params).reject { it.type.is_a? Types::Pad }
-              rbs_params = params.map { |it| "?#{it.name.as_variable_name}: #{it.type.rbs_type}" }.join(', ')
+              rbs_params = params.map { |it| "?#{it.name.as_variable_name}: #{parameter_rbs_type(it)}" }.join(', ')
               result = request_reply.reply ? reply_class : 'void'
               operation = method == 'dump' ? "::Nl::Async::Stream[#{result}]" : "::Nl::Async::Future[#{result}]"
+              yard_operation = method == 'dump' ? "Nl::Async::Stream<#{result}>" : "Nl::Async::Future<#{result}>"
 
               emit_comment(operation_doc(oper))
               emit_rbs_comment("(#{rbs_params}) -> #{operation}")
+              emit_yard_options(params)
+              emit_yard_return(yard_operation)
+              emit_yard_see(request_class)
               write("def #{method.as_method_name}_#{oper.name.as_method_name}(**args)")
               indent do
                 write("@exchange.call(#{method.as_symbol_literal}, #{request_class}, #{reply_class}, args)")
@@ -279,6 +385,8 @@ module Ynl
 
         emit_comment('Returns the asynchronous operation facade for this family.')
         emit_rbs_comment('(?stream_capacity: ::Integer?) -> AsyncOperations')
+        emit_yard_param('stream_capacity', '::Integer, nil')
+        emit_yard_return('AsyncOperations')
         write('def async(stream_capacity: nil)')
         indent do
           write('return @async_operations ||= build_async_facade(AsyncOperations) if stream_capacity.nil?')
@@ -329,20 +437,91 @@ module Ynl
       write('end')
     end
 
-    private def emit_const(name, value, rbs: nil)
+    private def emit_const(name, value, rbs: nil, internal: false)
+      emit_internal if internal
       write(name, ' = ', value, *([' #: ', rbs] if rbs))
     end
 
+    private def emit_value_definitions(namespace, definitions)
+      return if definitions.empty?
+
+      emit_module(namespace) do
+        definitions.each do |definition|
+          emit_comment(definition.doc)
+          emit_module(definition.name.as_class_name) do
+            definition.entries.each do |entry|
+              emit_comment(entry.doc)
+              emit_const(entry.name.as_class_name, yield(definition, entry))
+            end
+          end
+        end
+      end
+    end
+
+    private def enums_used_as_flags
+      @ynl.attribute_sets.each_value.flat_map(&:attributes).filter_map do |attribute|
+        next unless attribute.enum_as_flags && attribute.enum.is_a?(Models::Enum)
+
+        attribute.enum
+      end.uniq
+    end
+
     private def emit_getter(name, expr)
       write('def ', name, '; ', expr, '; end')
     end
 
-    private def emit_nodoc
-      write('# :nodoc:')
+    private def emit_internal
+      write('# @private')
+    end
+
+    private def emit_open(raw:, default_resolver:, classname:)
+      resolver_rbs = unless raw
+        type = '^(::Nl::Genl::Client, ::String) -> ::Nl::Genl::FamilyInfo'
+        default_resolver ? "?resolver: #{type}" : "resolver: #{type}"
+      end
+      rbs_params = [
+        resolver_rbs,
+        '?executor: executor?',
+        '?notification_capacity: ::Integer?',
+      ].compact.join(', ')
+      emit_rbs_comment(
+        "(#{rbs_params}) -> (::Nl::Family::Session & instance)",
+        "| [R] (#{rbs_params}) { (instance) -> R } -> R",
+      )
+
+      resolver_ruby = unless raw
+        default_resolver ? "resolver: #{default_resolver}" : 'resolver:'
+      end
+      ruby_params = [
+        resolver_ruby,
+        'executor: nil',
+        'notification_capacity: DEFAULT_NOTIFICATION_CAPACITY',
+      ].compact.join(', ')
+      emit_yard_overload("open(#{ruby_params})") do |indentation|
+        emit_yard_open_params(resolver: !raw, indentation:)
+        emit_yard_return(classname, indentation:)
+      end
+      emit_yard_overload("open(#{ruby_params}, &block)") do |indentation|
+        emit_yard_open_params(resolver: !raw, indentation:)
+        emit_yard_yieldparam('family', classname, indentation:)
+        emit_yard_return('Object', 'the result of the block', indentation:)
+      end
+      write("def self.open(#{ruby_params})")
+      indent { write('super') }
+      write('end')
+    end
+
+    private def emit_yard_open_params(resolver:, indentation: '')
+      emit_yard_param('resolver', '#call', indentation:) if resolver
+      emit_yard_param('executor', 'Symbol, nil', indentation:)
+      emit_yard_param('notification_capacity', 'Integer, nil', indentation:)
     end
 
     private def emit_comment(comment)
       return unless comment
+      comment = comment.gsub(KERNEL_DOC_REFERENCE) do |reference|
+        "{https://docs.kernel.org/#{$~[:path]}.html #{reference}}"
+      end
       comment.each_line(chomp: true) do |line|
         write('# ', line)
       end
@@ -385,7 +564,7 @@ module Ynl
 
     private def emit_message_class(name, message, fixed_header:, attribute_set:, doc:)
       emit_comment(doc)
-      emit_class(name, "#{@protocol}::Message") do
+      emit_class(name, "#@wire::Message") do
         emit_const('TYPE', message.value)
         emit_const('FIXED_HEADER', fixed_header&.then { 'Structs::' + it.name.as_class_name } || 'nil')
         emit_const('ATTRIBUTE_SET', "AttributeSets::#{attribute_set.name.as_class_name}")
@@ -396,21 +575,29 @@ module Ynl
           datatype = member.type
           next if datatype.is_a? Types::Pad
           next if attribute_params.include?(param)
-          emit_comment("Gets the value of `#{param}` field in the message's fixed header.")
-          emit_rbs_comment('return: ' + datatype.rbs_type)
+          emit_comment(member.doc)
+          emit_rbs_comment('return: ' + struct_member_rbs_type(datatype))
+          emit_yard_return(struct_member_yard_type(datatype))
           emit_getter(param.as_method_name, "fixed_header.#{param.as_method_name}")
         end
         attribute_params.each do |param|
-          datatype = attribute_set.attributes.find { it.name == param }.type
+          attribute = attribute_set.attributes.find { it.name == param }
+          datatype = attribute.type
           next if datatype.is_a? Types::Pad
           extending = fixed_header&.members&.any? { it.name == param }
 
-          if extending
-            emit_comment("Gets the value of `#{param}` attribute or fixed header in the message.")
-          else
-            emit_comment("Gets the value of `#{param}` attribute in the message.")
+          if extending && attribute.multi?
+            raise ParseError, "Multi-attribute #{param.inspect} conflicts with a fixed-header member"
+          end
+
+          emit_comment(attribute_doc(attribute))
+          emit_rbs_comment('return: ' + attribute_rbs_type(attribute))
+          emit_yard_return(attribute_yard_type(attribute))
+          emit_yard_see("AttributeSets::#{attribute_set.name.as_class_name}::#{attribute.name.as_class_name}")
+          if attribute.multi?
+            emit_getter(param.as_method_name, "attributes[#{param.as_variable_name.as_symbol_literal}].map(&:value)")
+            next
           end
-          emit_rbs_comment('return: ' + datatype.rbs_type)
           if extending
             emit_getter(param.as_method_name, "attributes[#{param.as_variable_name.as_symbol_literal}]&.value || fixed_header.#{param.as_method_name}")
           else
@@ -420,6 +607,214 @@ module Ynl
       end
     end
 
+    private def emit_sub_messages
+      return if @ynl.sub_messages.empty?
+
+      emit_module('SubMessages') do
+        @ynl.sub_messages.each_value do |sub_message|
+          grouped = sub_message.formats.group_by { it.value.as_class_name }
+          if collision = grouped.find { |_name, formats| formats.length > 1 }
+            ruby_name, formats = collision
+            raise ParseError,
+              "Sub-message formats #{formats.map(&:value).map(&:inspect).join(' and ')} normalize to #{ruby_name.inspect}"
+          end
+          emit_module(sub_message.name.as_class_name) do
+            sub_message.formats.each do |format|
+              emit_sub_message_class(format.value.as_class_name, format)
+            end
+          end
+        end
+      end
+    end
+
+    private def emit_sub_message_class(name, format)
+      emit_class(name, '::Nl::SubMessage') do
+        emit_const('FIXED_HEADER', format.fixed_header&.then { 'Structs::' + it.name.as_class_name } || 'nil')
+        emit_const('ATTRIBUTE_SET', format.attribute_set&.then { 'AttributeSets::' + it.name.as_class_name } || 'nil')
+
+        format.fixed_header&.members&.each do |member|
+          next if member.type.is_a?(Types::Pad)
+          extending = format.attribute_set&.attributes&.any? { it.name == member.name }
+          next if extending
+          emit_comment(member.doc)
+          emit_rbs_comment('return: ' + struct_member_rbs_type(member.type))
+          emit_yard_return(struct_member_yard_type(member.type))
+          emit_getter(member.name.as_method_name, "fixed_header.#{member.name.as_method_name}")
+        end
+
+        format.attribute_set&.attributes&.each do |attribute|
+          next if attribute.type.is_a?(Types::Pad)
+          extending = format.fixed_header&.members&.any? { it.name == attribute.name }
+          emit_comment(attribute_doc(attribute))
+          emit_rbs_comment('return: ' + attribute_rbs_type(attribute))
+          emit_yard_return(attribute_yard_type(attribute))
+          emit_yard_see("AttributeSets::#{format.attribute_set.name.as_class_name}::#{attribute.name.as_class_name}")
+          expression = if attribute.multi?
+            "attributes[#{attribute.name.as_variable_name.as_symbol_literal}].map(&:value)"
+          elsif extending
+            "attributes[#{attribute.name.as_variable_name.as_symbol_literal}]&.value || fixed_header.#{attribute.name.as_method_name}"
+          else
+            "attributes[#{attribute.name.as_variable_name.as_symbol_literal}]&.value"
+          end
+          emit_getter(attribute.name.as_method_name, expression)
+        end
+      end
+    end
+
+    private def parameter_rbs_type(param)
+      if param.is_a?(Models::AttributeSet::Attribute)
+        type = input_rbs_type(param.type)
+        param.multi? ? "::Array[#{type}]" : type
+      else
+        struct_member_rbs_type(param.type)
+      end
+    end
+
+    private def parameter_yard_type(param)
+      if param.is_a?(Models::AttributeSet::Attribute)
+        type = input_yard_type(param.type)
+        param.multi? ? "Array<#{type}>" : type
+      else
+        struct_member_yard_type(param.type)
+      end
+    end
+
+    private def struct_member_rbs_type(type)
+      if type.is_a?(Types::Binary) && type.struct
+        'Structs::' + type.struct.name.as_class_name
+      else
+        type.rbs_type
+      end
+    end
+
+    private def struct_member_yard_type(type)
+      if type.is_a?(Types::Binary) && type.struct
+        'Structs::' + type.struct.name.as_class_name
+      else
+        yard_type(type)
+      end
+    end
+
+    private def input_rbs_type(type)
+      case type
+      when Types::NestedAttributes
+        "(#{type.rbs_type} | ::Hash[::Symbol, untyped])"
+      when Types::Binary
+        type.struct ? "(#{type.rbs_type} | ::Hash[::Symbol, untyped])" : type.rbs_type
+      when Types::PackedArray
+        "::Array[#{input_rbs_type(type.sub_type)}]"
+      when Types::NestTypeValue
+        value_type = "(AttributeSets::#{type.attribute_set.name.as_class_name} | ::Hash[::Symbol, untyped])"
+        type.type_values.length.times { value_type = "::Hash[::Integer, #{value_type}]" }
+        value_type
+      when Types::IndexedArray
+        "::Array[#{input_rbs_type(type.sub_type)}]"
+      when Types::SubMessage
+        "(#{sub_message_rbs_type(type)} | ::Hash[::Symbol, untyped])"
+      else
+        type.rbs_type
+      end
+    end
+
+    private def input_yard_type(type)
+      case type
+      when Types::NestedAttributes
+        "#{yard_type(type)}, Hash<Symbol, Object>"
+      when Types::Binary
+        type.struct ? "#{yard_type(type)}, Hash<Symbol, Object>" : yard_type(type)
+      when Types::PackedArray, Types::IndexedArray
+        "Array<#{input_yard_type(type.sub_type)}>"
+      when Types::NestTypeValue
+        value_type = "AttributeSets::#{type.attribute_set.name.as_class_name}, Hash<Symbol, Object>"
+        type.type_values.length.times { value_type = "Hash<Integer, #{value_type}>" }
+        value_type
+      when Types::SubMessage
+        "#{sub_message_yard_type(type)}, Hash<Symbol, Object>"
+      else
+        yard_type(type)
+      end
+    end
+
+    private def attribute_rbs_type(attribute)
+      type = if attribute.type.is_a?(Types::SubMessage)
+        sub_message_rbs_type(attribute.type)
+      else
+        attribute.type.rbs_type
+      end
+      attribute.multi? ? "::Array[#{type}]" : type
+    end
+
+    private def attribute_yard_type(attribute)
+      type = if attribute.type.is_a?(Types::SubMessage)
+        sub_message_yard_type(attribute.type)
+      else
+        yard_type(attribute.type)
+      end
+      attribute.multi? ? "Array<#{type}>" : type
+    end
+
+    private def attribute_doc(attribute)
+      return attribute.doc unless attribute.enum
+
+      definition = "{#{attribute_value_definition(attribute)}}"
+      value_doc = if attribute.enum_as_flags || attribute.enum.is_a?(Models::Flags)
+        "Known flags are defined in #{definition}."
+      else
+        "Known enum values are defined in #{definition}."
+      end
+      [attribute.doc, value_doc].compact.reject(&:empty?).join("\n\n")
+    end
+
+    private def attribute_value_definition(attribute)
+      namespace = if attribute.enum_as_flags || attribute.enum.is_a?(Models::Flags)
+        'Flags'
+      else
+        'Enums'
+      end
+      "#{namespace}::#{attribute.enum.name.as_class_name}"
+    end
+
+    private def sub_message_rbs_type(type)
+      formats = type.sub_message.formats.map do |format|
+        "SubMessages::#{type.sub_message.name.as_class_name}::#{format.value.as_class_name}"
+      end
+      (formats << '::Nl::RawSubMessage').join(' | ')
+    end
+
+    private def sub_message_yard_type(type)
+      formats = type.sub_message.formats.map do |format|
+        "SubMessages::#{type.sub_message.name.as_class_name}::#{format.value.as_class_name}"
+      end
+      (formats << 'Nl::RawSubMessage').join(', ')
+    end
+
+    private def yard_type(type)
+      case type
+      when Types::Scalar, Types::Flag
+        'Integer'
+      when Types::String
+        'String'
+      when Types::Binary
+        type.struct ? 'Structs::' + type.struct.name.as_class_name : 'String'
+      when Types::PackedArray, Types::IndexedArray
+        "Array<#{yard_type(type.sub_type)}>"
+      when Types::NestedAttributes
+        'AttributeSets::' + type.attribute_set.name.as_class_name
+      when Types::NestTypeValue
+        value_type = 'AttributeSets::' + type.attribute_set.name.as_class_name
+        type.type_values.length.times { value_type = "Hash<Integer, #{value_type}>" }
+        value_type
+      when Types::SubMessage
+        'Nl::SubMessage'
+      when Types::Pad
+        'nil'
+      when Types::Bitfield32
+        'Nl::Bitfield32'
+      else
+        raise "Unknown YARD type: #{type.class}"
+      end
+    end
+
     private def emit_mcast_groups
       groups = @ynl.mcast_groups.values
       grouped = groups.group_by { it.name.as_variable_name }
@@ -431,67 +826,419 @@ module Ynl
 
       entries = groups.map do |group|
         key = group.name.as_variable_name.as_symbol_literal
-        value = "::Nl::McastGroup.new(#{group.name.as_string_literal}, #{group.value.inspect})"
+        value = "::Nl::McastGroup.new(#{group.name.as_string_literal}, #{mcast_group_value_literal(group.value)})"
         "#{key} => #{value}"
       end
       emit_const(
         'MCAST_GROUPS',
         "Ractor.make_shareable({#{entries.join(', ')}})",
         rbs: 'Hash[::Symbol, ::Nl::McastGroup]',
+        internal: true,
       )
     end
 
     private def emit_subscription_methods
-      group_type = @ynl.mcast_groups.values
+      groups = @ynl.mcast_groups.values
         .map { ":#{it.name.as_variable_name}" }
-        .join(' | ')
-      emit_rbs_comment("(*(#{group_type}) groups) -> self")
+      emit_rbs_comment("(*(#{groups.join(' | ')}) groups) -> self")
+      emit_yard_param('groups', "Array<#{groups.join(', ')}>")
+      emit_yard_return('self')
       write('def subscribe(*groups) = super')
-      emit_rbs_comment("(*(#{group_type}) groups) -> self")
+      emit_rbs_comment("(*(#{groups.join(' | ')}) groups) -> self")
+      emit_yard_param('groups', "Array<#{groups.join(', ')}>")
+      emit_yard_return('self')
       write('def unsubscribe(*groups) = super')
     end
 
     private def emit_rbs_comment(*args)
-      write('#--')
       args.each do |arg|
         emit_comment('@rbs ' + arg)
       end
     end
 
-    private def to_datatype(type, checks)
+    private def emit_yard_overload(signature)
+      emit_comment("@overload #{signature}")
+      yield '  '
+    end
+
+    private def emit_yard_options(params, indentation: '')
+      emit_yard_param('args', 'Hash', indentation:)
+      params.each do |param|
+        emit_yard_option(
+          'args',
+          param.name.as_variable_name,
+          parameter_yard_type(param),
+          param.is_a?(Models::AttributeSet::Attribute) ? attribute_doc(param) : param.doc,
+          indentation:,
+        )
+      end
+    end
+
+    private def emit_yard_option(parameter, name, type, description, indentation: '')
+      lines = description&.each_line(chomp: true)&.to_a || []
+      emit_comment(["#{indentation}@option #{parameter} [#{type}] #{name}", lines.shift].compact.join(' '))
+      lines.each do |line|
+        emit_comment("#{indentation}  #{line}")
+      end
+    end
+
+    private def emit_yard_attribute(name, type, description)
+      emit_comment("@!attribute [rw] #{name}")
+      description&.each_line(chomp: true) do |line|
+        emit_comment("  #{line}")
+      end
+      emit_comment("  @return [#{type}]")
+    end
+
+    private def emit_yard_param(name, type, indentation: '')
+      emit_comment("#{indentation}@param [#{type}] #{name}")
+    end
+
+    private def emit_yard_return(type, description = nil, indentation: '')
+      emit_comment(["#{indentation}@return [#{type}]", description].compact.join(' '))
+    end
+
+    private def emit_yard_see(object)
+      emit_comment("@see #{object}")
+    end
+
+    private def emit_yard_yieldparam(name, type, indentation: '')
+      emit_comment("#{indentation}@yieldparam [#{type}] #{name}")
+    end
+
+    private def build_selector_plan
+      sets = @ynl.attribute_sets.values
+      @local_selectors = sets.to_h { [it, []] }
+      @external_selectors = sets.to_h { [it, []] }
+
+      @ynl.sub_messages.each_value do |sub_message|
+        duplicate = sub_message.formats.group_by(&:value).find { |_value, formats| formats.length > 1 }
+        if duplicate
+          raise ParseError,
+            "Duplicate format value #{duplicate.first.inspect} in sub-message #{sub_message.name.inspect}"
+        end
+      end
+
+      changed = true
+      while changed
+        changed = false
+        sets.each do |set|
+          set.attributes.each do |attribute|
+            if attribute.type.is_a?(Types::SubMessage)
+              changed |= require_selector(set, attribute.type.selector)
+            end
+
+            child_attribute_sets(attribute.type).each do |child|
+              @external_selectors.fetch(child).each do |selector|
+                changed |= require_selector(set, selector)
+              end
+            end
+          end
+        end
+      end
+
+      build_attribute_orders
+      roots = @ynl.operations.values.filter_map(&:attribute_set).uniq
+      roots.each do |root|
+        required = @external_selectors.fetch(root)
+        next if required.empty?
+        raise ParseError,
+          "Root attribute set #{root.name.inspect} requires external selectors: #{required.join(', ')}"
+      end
+      build_selector_sources(roots)
+      validate_selector_values
+    end
+
+    private def require_selector(set, selector)
+      local = attribute_by_name(set, selector)
+      if local&.multi?
+        raise ParseError,
+          "Multi-attribute #{selector.inspect} cannot be a selector in attribute set #{set.name.inspect}"
+      end
+      target = local ? @local_selectors : @external_selectors
+      selectors = target.fetch(set)
+      return false if selectors.include?(selector)
+      selectors << selector
+      true
+    end
+
+    private def build_attribute_orders
+      @attribute_orders = {}
+      @ynl.attribute_sets.each_value do |set|
+        dependencies = set.attributes.to_h { |attribute| [attribute, []] }
+        set.attributes.each do |attribute|
+          selectors = []
+          selectors << attribute.type.selector if attribute.type.is_a?(Types::SubMessage)
+          child_attribute_sets(attribute.type).each do |child|
+            selectors.concat(@external_selectors.fetch(child))
+          end
+
+          selectors.uniq.each do |selector|
+            selector_attribute = attribute_by_name(set, selector)
+            dependencies.fetch(attribute) << selector_attribute if selector_attribute
+          end
+        end
+
+        ordered = []
+        remaining = set.attributes.dup
+        until remaining.empty?
+          index = remaining.index do |attribute|
+            dependencies.fetch(attribute).all? { ordered.include?(it) }
+          end
+          unless index
+            raise ParseError,
+              "Selector dependency cycle in attribute set #{set.name.inspect}: #{remaining.map(&:name).join(', ')}"
+          end
+          ordered << remaining.delete_at(index)
+        end
+        @attribute_orders[set] = ordered.each_with_index.to_h
+      end
+    end
+
+    private def build_selector_sources(roots)
+      @selector_sources = @ynl.attribute_sets.values.to_h { [it, Hash.new { |h, k| h[k] = [] }] }
+      reached = roots.to_h { [it, true] }
+
+      changed = true
+      while changed
+        changed = false
+        reached.keys.each do |set|
+          set.attributes.each do |attribute|
+            child_attribute_sets(attribute.type).each do |child|
+              unless reached[child]
+                reached[child] = true
+                changed = true
+              end
+              @external_selectors.fetch(child).each do |selector|
+                sources = if source = attribute_by_name(set, selector)
+                  [source]
+                else
+                  @selector_sources.fetch(set)[selector]
+                end
+                target = @selector_sources.fetch(child)[selector]
+                sources.each do |candidate|
+                  unless target.include?(candidate)
+                    target << candidate
+                    changed = true
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+
+    private def validate_selector_values
+      @ynl.attribute_sets.each_value do |set|
+        set.attributes.each do |attribute|
+          next unless attribute.type.is_a?(Types::SubMessage)
+          keys = attribute.type.sub_message.formats.map do |format|
+            selector_value_literal(set, attribute.type.selector, format.value)
+          end
+          duplicate = keys.group_by(&:itself).find { |_key, matches| matches.length > 1 }
+          if duplicate
+            raise ParseError,
+              "Sub-message #{attribute.type.sub_message.name.inspect} has duplicate compiled selector value #{duplicate.first}"
+          end
+        end
+      end
+    end
+
+    private def child_attribute_sets(type)
+      case type
+      when Types::NestedAttributes, Types::NestTypeValue
+        [type.attribute_set]
+      when Types::IndexedArray
+        child_attribute_sets(type.sub_type)
+      when Types::SubMessage
+        type.sub_message.formats.filter_map(&:attribute_set)
+      else
+        []
+      end
+    end
+
+    private def attribute_by_name(set, name)
+      set.attributes.find { it.name == name }
+    end
+
+    private def selector_source_literal(set, selector)
+      if (index = @local_selectors.fetch(set).index(selector))
+        "::Nl::Selector::Local.new(#{index})"
+      elsif (index = @external_selectors.fetch(set).index(selector))
+        "::Nl::Selector::External.new(#{index})"
+      else
+        raise ParseError, "Unresolved selector #{selector.inspect} in attribute set #{set.name.inspect}"
+      end
+    end
+
+    private def selector_bindings_literal(parent, child)
+      return '[]' unless child
+      bindings = @external_selectors.fetch(child).map do |selector|
+        selector_source_literal(parent, selector)
+      end
+      "Ractor.make_shareable([#{bindings.join(', ')}])"
+    end
+
+    private def selector_value_literal(set, selector, format_value)
+      sources = if source = attribute_by_name(set, selector)
+        [source]
+      else
+        @selector_sources.fetch(set)[selector]
+      end
+      if sources.empty?
+        raise ParseError,
+          "Cannot determine the type of external selector #{selector.inspect} in attribute set #{set.name.inspect}"
+      end
+
+      values = sources.map do |source|
+        case source.type
+        when Types::String
+          format_value.as_string_literal
+        when Types::Scalar
+          unless source.enum.is_a?(Models::Enum)
+            raise ParseError,
+              "Integer selector #{source.name.inspect} must reference an enum"
+          end
+          entry = source.enum.entries.find { it.name == format_value }
+          unless entry
+            raise ParseError,
+              "Selector enum #{source.enum.name.inspect} has no entry #{format_value.inspect}"
+          end
+          entry.value.to_s
+        else
+          raise ParseError,
+            "Selector #{source.name.inspect} must be a string or an enum-backed integer"
+        end
+      end.uniq
+      if values.length != 1
+        raise ParseError,
+          "Selector #{selector.inspect} has incompatible definitions for format #{format_value.inspect}"
+      end
+      values.first
+    end
+
+    private def to_datatype(type, checks, owner: nil)
       case type
       when Types::Pad
-        "#{@protocol}::DataTypes::Pad.new(#{type.length})"
+        "::Nl::DataTypes::Pad.new(#{type.length})"
       when Types::Flag
-        "#{@protocol}::DataTypes::Flag.new"
+        "::Nl::DataTypes::Flag.new"
       when Types::Bitfield32
-        "#{@protocol}::DataTypes::Bitfield32.new"
+        "::Nl::DataTypes::Bitfield32.new"
       when Types::Scalar
-        "#{@protocol}::DataTypes::Scalar.new(::Nl::Endian::#{type.byte_order.name.as_class_name}::#{type.type.as_const_name}, check: #{to_checks(checks)})"
+        byte_order = "::Nl::Endian::#{type.byte_order.name.as_class_name}"
+        if ['sint', 'uint'].include?(type.type)
+          "::Nl::DataTypes::VariableInteger.new(#{byte_order}, signed: #{type.type == 'sint'}, check: #{to_checks(checks)})"
+        else
+          "::Nl::DataTypes::Scalar.new(#{byte_order}::#{type.type.as_const_name}, check: #{to_checks(checks)})"
+        end
       when Types::String
-        "#{@protocol}::DataTypes::String.new(check: #{to_checks(checks)})"
+        "::Nl::DataTypes::String.new(check: #{to_checks(checks)})"
       when Types::Binary
-        # if type.struct
-        #   "Structs::" + type.struct.name.as_class_name
-        # else
-        "#{@protocol}::DataTypes::Binary.new(check: #{to_checks(checks)})"
-        # end
+        if type.struct
+          "::Nl::DataTypes::Struct.new(Structs::#{type.struct.name.as_class_name}, check: #{to_checks(checks)}, consume_remaining: true)"
+        else
+          "::Nl::DataTypes::Binary.new(check: #{to_checks(checks)})"
+        end
+      when Types::PackedArray
+        "::Nl::DataTypes::PackedArray.new(#{to_datatype(type.sub_type, nil)}, check: #{to_checks(checks)})"
       when Types::NestedAttributes
-        "#{@protocol}::DataTypes::NestedAttributes.new(#{type.attribute_set.name.as_class_name})"
+        bindings = selector_bindings_literal(owner, type.attribute_set)
+        "::Nl::DataTypes::NestedAttributes.new(AttributeSets::#{type.attribute_set.name.as_class_name}, selector_bindings: #{bindings})"
       when Types::NestTypeValue
-        "#{@protocol}::DataTypes::NestTypeValue.new(#{type.attribute_set.name.as_class_name}, #{type.type_values.length})"
+        bindings = selector_bindings_literal(owner, type.attribute_set)
+        "::Nl::DataTypes::NestTypeValue.new(AttributeSets::#{type.attribute_set.name.as_class_name}, #{type.type_values.length}, selector_bindings: #{bindings})"
       when Types::IndexedArray
-        "#{@protocol}::DataTypes::IndexedArray.new(#{to_datatype(type.sub_type, nil)})"
+        "::Nl::DataTypes::IndexedArray.new(#{to_datatype(type.sub_type, nil, owner:)})"
       when Types::SubMessage
-        "#{@protocol}::DataTypes::Binary.new(check: nil)"
+        selector = selector_source_literal(owner, type.selector)
+        formats = type.sub_message.formats.map do |format|
+          key = selector_value_literal(owner, type.selector, format.value)
+          klass = "SubMessages::#{type.sub_message.name.as_class_name}::#{format.value.as_class_name}"
+          bindings = selector_bindings_literal(owner, format.attribute_set)
+          nested = !format.attribute_set.nil?
+          "#{key} => ::Nl::DataTypes::SubMessage::Format.new(#{klass}, #{bindings}, #{nested})"
+        end
+        "::Nl::DataTypes::SubMessage.new(#{selector}, {#{formats.join(', ')}})"
       else
         raise "Unknown type: #{type.class}"
       end
     end
 
+    private def to_struct_member_datatype(type)
+      if type.is_a?(Types::Binary) && type.struct
+        "::Nl::DataTypes::Struct.new(Structs::#{type.struct.name.as_class_name}, check: nil)"
+      elsif type.is_a?(Types::Binary)
+        "::Nl::DataTypes::Binary.new(length: #{type.length}, check: nil)"
+      else
+        to_datatype(type, nil)
+      end
+    end
+
     private def to_checks(checks)
       return 'nil' if !checks || checks.empty?
-      %Q{-> { #{checks.join('; ')} }}
+      %Q{-> { #{checks.map { to_check(it) }.join('; ')} }}
+    end
+
+    private def to_check(check)
+      value = case check.value
+      when Models::Const
+        "Constants::#{check.value.name.as_const_name}"
+      else
+        integer_literal(check.value)
+      end
+
+      comparison, description = case check.operation
+      when 'max'
+        ["it <= #{value}", "greater than maximum #{check_message_value(check, value)}"]
+      when 'min'
+        ["it >= #{value}", "less than minimum #{check_message_value(check, value)}"]
+      when 'min-len'
+        ["it.bytesize >= #{value}", "shorter than minimum length #{check_message_value(check, value)}"]
+      when 'max-len'
+        ["it.bytesize <= #{value}", "longer than maximum length #{check_message_value(check, value)}"]
+      when 'exact-len'
+        ["it.bytesize == #{value}", "not equal to length #{check_message_value(check, value)}"]
+      else
+        raise "Unknown check: #{check.operation}"
+      end
+
+      %Q{raise ArgumentError, "Value \#{it.inspect} is #{description}" unless #{comparison}}
+    end
+
+    private def check_message_value(check, value)
+      check.value.is_a?(Models::Const) ? "\#{#{value}}" : value
+    end
+
+    private def const_value_literal(value)
+      case value
+      when Integer
+        value.to_s
+      when String
+        value.as_string_literal
+      else
+        raise ParseError, "YNL constant value must be a string or an integer, got #{value.class}"
+      end
+    end
+
+    private def integer_literal(value)
+      unless value.is_a?(Integer)
+        raise ParseError, "YNL check value must be an integer, got #{value.class}"
+      end
+
+      value.to_s
+    end
+
+    private def mcast_group_value_literal(value)
+      case value
+      when Integer
+        value.to_s
+      when nil
+        'nil'
+      else
+        raise ParseError, "YNL multicast group value must be an integer, got #{value.class}"
+      end
     end
   end
 end