yard 0.9.28 → 0.9.43

data/lib/yard/handlers/rbs/method_handler.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+# Handles RBS method definitions (def name: signature).
+#
+# Creates a {YARD::CodeObjects::MethodObject} for each declaration
+# and infers @param, @return, @yield, and @yieldparam tags from the
+# RBS type signature when those tags are absent from the docstring.
+class YARD::Handlers::RBS::MethodHandler < YARD::Handlers::RBS::Base
+  handles :method_def
+
+  process do
+    meth_scope = statement.visibility == :class ? :class : :instance
+    obj = register MethodObject.new(namespace, statement.name, meth_scope)
+    apply_signature_tags(obj, statement.signatures)
+
+    # For initialize, ensure the return type is the class, not void.
+    if statement.name == 'initialize'
+      ret_tags = obj.tags(:return)
+      if ret_tags.none? || (ret_tags.length == 1 && ret_tags.first.types == ['void'])
+        obj.docstring.delete_tags(:return)
+        obj.add_tag YARD::Tags::Tag.new(:return, "a new instance of #{namespace.name}",
+                                        [namespace.name.to_s])
+      end
+    end
+  end
+
+  # Convert an RBS type string to an array of YARD type strings.
+  #
+  # @param rbs [String] e.g. "String | Integer", "Array[String]", "bool"
+  # @return [Array<String>]
+  def self.rbs_type_to_yard_types(rbs)
+    rbs = rbs.strip
+    return ['void']    if rbs == 'void'
+    return ['Boolean'] if rbs == 'bool'
+    return ['Object']  if rbs == 'untyped'
+    return ['nil']     if rbs == 'nil'
+
+    # Strip outer parentheses: `(String | Integer)` → recurse on inner.
+    if rbs.start_with?('(') && rbs.end_with?(')') && bracket_depth(rbs[1..-2]) == 0
+      return rbs_type_to_yard_types(rbs[1..-2])
+    end
+
+    # `Type?` is shorthand for `Type | nil` when the ? is outermost.
+    if rbs =~ /\A(.+)\?\z/ && bracket_depth($1) == 0
+      return rbs_type_to_yard_types($1) + ['nil']
+    end
+
+    split_on_pipe(rbs).map { |t| t.strip }
+  end
+
+  private
+
+  # Apply tags from all overload signatures to the method object.
+  def apply_signature_tags(obj, sigs)
+    return if sigs.nil? || sigs.empty?
+
+    if sigs.length == 1
+      # Single signature: add @param and @return directly.
+      add_param_return_tags(obj, sigs.first)
+    else
+      # Multiple signatures: add @overload tags.
+      sigs.each { |sig| add_overload_tag(obj, statement.name, sig) }
+    end
+  end
+
+  # Add @param / @return / @yield / @yieldparam from a single overload sig.
+  def add_param_return_tags(obj, sig)
+    parsed = parse_function_type(sig)
+
+    parsed[:params].each do |p|
+      next if p[:block]  # block param handled via @yield below
+      tag_name = p[:name] ? p[:name].to_s : nil
+      next if tag_name && obj.tags(:param).any? { |t| t.name == tag_name }
+      obj.add_tag YARD::Tags::Tag.new(:param, '', p[:types], tag_name)
+    end
+
+    if (blk = parsed[:block_param])
+      add_yield_tags(obj, blk)
+    end
+
+    unless obj.has_tag?(:return)
+      obj.add_tag YARD::Tags::Tag.new(:return, '', parsed[:return_types])
+    end
+  end
+
+  # Add an @overload tag for one signature overload.
+  def add_overload_tag(obj, meth_name, sig)
+    parsed     = parse_function_type(sig)
+    param_sigs = parsed[:params].reject { |p| p[:block] }.map.with_index do |p, idx|
+      p[:name] || "arg#{idx}"
+    end
+
+    # Build the overload tag text:  signature line + nested @param/@return lines.
+    lines = ["#{meth_name}(#{param_sigs.join(', ')})"]
+    parsed[:params].reject { |p| p[:block] }.each_with_index do |p, idx|
+      pname = p[:name] || "arg#{idx}"
+      lines << "  @param #{pname} [#{p[:types].join(', ')}]"
+    end
+
+    if (blk = parsed[:block_param])
+      add_yield_tags(obj, blk)
+    end
+
+    lines << "  @return [#{parsed[:return_types].join(', ')}]"
+    obj.add_tag YARD::Tags::OverloadTag.new(:overload, lines.join("\n"))
+  end
+
+  # Add @yield and @yieldparam tags from a parsed block type.
+  def add_yield_tags(obj, blk)
+    return if obj.has_tag?(:yield) && obj.has_tag?(:yieldparam)
+    obj.add_tag YARD::Tags::Tag.new(:yield, '') unless obj.has_tag?(:yield)
+    blk[:params].each_with_index do |p, idx|
+      pname = p[:name] || "arg#{idx}"
+      next if obj.tags(:yieldparam).any? { |t| t.name == pname }
+      obj.add_tag YARD::Tags::Tag.new(:yieldparam, '', p[:types], pname)
+    end
+    unless obj.has_tag?(:yieldreturn)
+      obj.add_tag YARD::Tags::Tag.new(:yieldreturn, '', self.class.rbs_type_to_yard_types(blk[:return_type] || 'void'))
+    end
+  end
+
+  # Parse a single RBS function type string (one overload) into its components.
+  #
+  # @param sig [String] e.g. "(String name, Integer age) -> String"
+  # @return [Hash] { :params => [...], :block_param => Hash|nil, :return_types => [...] }
+  def parse_function_type(sig)
+    sig = sig.strip
+    return { :params => [], :block_param => nil, :return_types => ['void'] } if sig.empty?
+
+    remaining = sig
+    params = []
+    block_param = nil
+
+    # 1. Extract positional/keyword params: leading `(...)`.
+    if remaining.start_with?('(')
+      close = find_matching(remaining, 0, '(', ')')
+      raise YARD::Parser::UndocumentableError, "malformed signature (unclosed '('): #{sig}" if close.nil?
+      params_str = remaining[1...close]
+      remaining  = remaining[close + 1..-1].lstrip
+      params  = parse_params_list(params_str)
+    end
+
+    # 2. Extract block type: `{ ... }`.
+    if remaining.start_with?('{')
+      close = find_matching(remaining, 0, '{', '}')
+      raise YARD::Parser::UndocumentableError, "malformed signature (unclosed '{'): #{sig}" if close.nil?
+      block_inner  = remaining[1...close]
+      remaining    = remaining[close + 1..-1].lstrip
+      block_param  = parse_block_type(block_inner)
+    end
+
+    # 3. Return type after `->`.
+    return_types = if remaining =~ /\A->\s*(.*)\z/
+                     self.class.rbs_type_to_yard_types($1.strip)
+                   else
+                     ['void']
+                   end
+
+    { :params => params, :block_param => block_param, :return_types => return_types }
+  end
+
+  # Parse a comma-separated parameter list (content inside outer parens).
+  def parse_params_list(str)
+    str = str.strip
+    return [] if str.empty?
+
+    split_by_comma(str).map { |p| parse_single_param(p.strip) }.compact
+  end
+
+  # Parse one parameter from an RBS param list.
+  def parse_single_param(param)
+    return nil if param.empty?
+
+    optional = false
+    rest     = false
+
+    # Optional marker `?`.
+    if param.start_with?('?') && !param.start_with?('?(')
+      optional = true
+      param    = param[1..-1].lstrip
+    end
+
+    # Double-splat `**` (rest keyword).
+    if param.start_with?('**')
+      rest  = true
+      param = param[2..-1].lstrip
+    # Single-splat `*` (rest positional).
+    elsif param.start_with?('*') && !param.start_with?('*)')
+      rest  = true
+      param = param[1..-1].lstrip
+    end
+
+    # Block-type proc: `^(...)`.
+    if param.start_with?('^')
+      return { :name => nil, :types => [param], :optional => false, :rest => false, :block => true }
+    end
+
+    # Keyword parameter: `name: Type` or `?name: Type`.
+    if param =~ /\A([a-z_]\w*)\s*:\s*(.*)\z/ && !rest
+      kw_name = $1
+      kw_type = $2.strip
+      return { :name => "#{kw_name}:", :types => self.class.rbs_type_to_yard_types(kw_type),
+               :optional => optional, :rest => false }
+    end
+
+    # Positional: `Type [param_name]`.
+    type_str, param_name = extract_type_and_name(param)
+    { :name => param_name, :types => self.class.rbs_type_to_yard_types(type_str),
+      :optional => optional, :rest => rest }
+  end
+
+  # Split a type+name string like "Array[String] names" into ["Array[String]", "names"].
+  # The name is the trailing lowercase identifier (if any).
+  def extract_type_and_name(str)
+    str = str.strip
+    if str =~ /\A(.*\S)\s+([a-z_]\w*)\z/m
+      type_part = $1.strip
+      name_part = $2
+      # Exclude RBS type keywords from being mistaken for names.
+      unless %w[void untyped nil bool top bottom self instance class].include?(name_part)
+        return [type_part, name_part] unless type_part.empty?
+      end
+    end
+    [str, nil]
+  end
+
+  # Parse the inside of a `{ ... }` block type, e.g. "(Integer) -> String".
+  def parse_block_type(inner)
+    inner = inner.strip
+    params = []
+    ret    = nil
+
+    if inner.start_with?('(')
+      close  = find_matching(inner, 0, '(', ')')
+      raise YARD::Parser::UndocumentableError, "malformed block type (unclosed '('): #{inner}" if close.nil?
+      params = parse_params_list(inner[1...close])
+      rest   = inner[close + 1..-1].lstrip
+    else
+      rest = inner
+    end
+
+    ret = $1.strip if rest =~ /\A->\s*(.*)\z/
+    { :params => params, :return_type => ret }
+  end
+
+  # Find the index of the matching close bracket starting from +start+.
+  # @return [nil] if no matching bracket is found (malformed input).
+  def find_matching(str, start, open, close)
+    depth = 0
+    (start...str.length).each do |i|
+      case str[i]
+      when open  then depth += 1
+      when close
+        depth -= 1
+        return i if depth == 0
+      end
+    end
+    nil
+  end
+
+  # Split +str+ on commas that are not inside brackets.
+  def split_by_comma(str)
+    depth = 0
+    parts = []
+    cur   = String.new('')
+    str.each_char do |c|
+      case c
+      when '(', '[', '{'
+        depth += 1
+        cur << c
+      when ')', ']', '}'
+        depth -= 1
+        cur << c
+      when ','
+        if depth == 0
+          parts << cur.strip
+          cur = String.new('')
+        else
+          cur << c
+        end
+      else
+        cur << c
+      end
+    end
+    parts << cur.strip unless cur.strip.empty?
+    parts
+  end
+
+  # Split +str+ on `|` that are not inside brackets.
+  def self.split_on_pipe(str)
+    depth = 0
+    parts = []
+    cur   = String.new('')
+    str.each_char do |c|
+      case c
+      when '(', '[', '{'
+        depth += 1
+        cur << c
+      when ')', ']', '}'
+        depth -= 1
+        cur << c
+      when '|'
+        if depth == 0
+          parts << cur.strip
+          cur = String.new('')
+        else
+          cur << c
+        end
+      else
+        cur << c
+      end
+    end
+    parts << cur.strip unless cur.strip.empty?
+    parts
+  end
+
+  # Return the bracket depth of the full string (should be 0 for well-formed types).
+  def self.bracket_depth(str)
+    depth = 0
+    str.each_char do |c|
+      case c
+      when '(', '[', '{' then depth += 1
+      when ')', ']', '}' then depth -= 1
+      end
+    end
+    depth
+  end
+end

data/lib/yard/handlers/rbs/mixin_handler.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# Handles RBS include, extend, and prepend declarations.
+class YARD::Handlers::RBS::MixinHandler < YARD::Handlers::RBS::Base
+  handles :include, :extend, :prepend
+
+  process do
+    mixin = P(namespace, statement.mixin_name)
+    case statement.type
+    when :include
+      mixins = namespace.mixins(:instance)
+      mixins << mixin unless mixins.include?(mixin)
+    when :extend
+      mixins = namespace.mixins(:class)
+      mixins << mixin unless mixins.include?(mixin)
+    when :prepend
+      mixins = namespace.mixins(:instance)
+      mixins.unshift(mixin) unless mixins.include?(mixin)
+    end
+  end
+end

data/lib/yard/handlers/rbs/namespace_handler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# Handles RBS class, module, and interface declarations by registering
+# the corresponding namespace code objects and recursing into their bodies.
+class YARD::Handlers::RBS::NamespaceHandler < YARD::Handlers::RBS::Base
+  handles :class, :module, :interface
+  namespace_only
+
+  process do
+    name = statement.name
+    type = statement.type
+
+    obj = case type
+          when :class
+            klass = register ClassObject.new(namespace, name)
+            if (sc = statement.superclass) && !sc.strip.empty?
+              klass.superclass = P(namespace, sc)
+              klass.superclass.type = :class if klass.superclass.is_a?(Proxy)
+            end
+            klass
+          when :module, :interface
+            register ModuleObject.new(namespace, name)
+          end
+
+    parse_block(:namespace => obj)
+  end
+end

data/lib/yard/handlers/ruby/attribute_handler.rb

@@ -31,8 +31,6 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
 
     # Add all attributes
     validated_attribute_names(params).each do |name|
-      namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
-
       # Show their methods as well
       {:read => name, :write => "#{name}="}.each do |type, meth|
         if type == :read ? read : write
@@ -52,12 +50,17 @@ class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
           register(o)
           o.docstring = doc if o.docstring.blank?(false)
 
-          # Regsiter the object explicitly
-          namespace.attributes[scope][name][type] = o
+          # Register the object explicitly.
+          # Use o.scope rather than scope: register() may have changed o.scope
+          # via a @!scope directive, so the attribute must be stored under the
+          # method's final scope to keep attr_info's lookup consistent.
+          namespace.attributes[o.scope][name] ||= SymbolHash[:read => nil, :write => nil]
+          namespace.attributes[o.scope][name][type] = o
         else
           obj = namespace.children.find {|other| other.name == meth.to_sym && other.scope == scope }
 
           # register an existing method as attribute
+          namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
           namespace.attributes[scope][name][type] = obj if obj
         end
       end

data/lib/yard/handlers/ruby/constant_handler.rb

@@ -9,6 +9,9 @@ class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
     if statement[1].call? && statement[1][0][0] == s(:const, "Struct") &&
        statement[1][2] == s(:ident, "new")
       process_structclass(statement)
+    elsif statement[1].call? && statement[1][0][0] == s(:const, "Data") &&
+       statement[1][2] == s(:ident, "define")
+      process_dataclass(statement)
     elsif statement[0].type == :var_field && statement[0][0].type == :const
       process_constant(statement)
     elsif statement[0].type == :const_path_field
@@ -31,20 +34,35 @@ class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
   end
 
   def process_structclass(statement)
-    lhs = statement[0][0]
-    if lhs.type == :const
-      klass = create_class(lhs[0], P(:Struct))
+    lhs = statement[0]
+    if (lhs.type == :var_field && lhs[0].type == :const) || lhs.type == :const_path_field
+      klass = create_class(lhs.source, P(:Struct))
       create_attributes(klass, extract_parameters(statement[1]))
       parse_block(statement[1].block[1], :namespace => klass) unless statement[1].block.nil?
     else
-      raise YARD::Parser::UndocumentableError, "Struct assignment to #{statement[0].source}"
+      raise YARD::Parser::UndocumentableError, "Struct assignment to #{lhs.source}"
     end
   end
 
-  # Extract the parameters from the Struct.new AST node, returning them as a list
+  def process_dataclass(statement)
+    lhs = statement[0]
+    if (lhs.type == :var_field && lhs[0].type == :const) || lhs.type == :const_path_field
+      klass = create_class(lhs.source, P(:Data))
+      extract_parameters(statement[1]).each do |member|
+        next if klass.attributes[:instance][member]
+        klass.attributes[:instance][member] = SymbolHash[:read => nil, :write => nil]
+        create_reader(klass, member)
+      end
+      parse_block(statement[1].block[1], :namespace => klass) unless statement[1].block.nil?
+    else
+      raise YARD::Parser::UndocumentableError, "Data assignment to #{lhs.source}"
+    end
+  end
+
+  # Extract the parameters from the Struct.new or Data.define AST node, returning them as a list
   # of strings
   #
-  # @param [MethodCallNode] superclass the AST node for the Struct.new call
+  # @param [MethodCallNode] superclass the AST node for the Struct.new or Data.define call
   # @return [Array<String>] the member names to generate methods for
   def extract_parameters(superclass)
     return [] unless superclass.parameters

data/lib/yard/handlers/ruby/legacy/attribute_handler.rb

@@ -51,7 +51,7 @@ class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Leg
           register(o)
           o.docstring = doc if o.docstring.blank?(false)
 
-          # Regsiter the object explicitly
+          # Register the object explicitly
           namespace.attributes[scope][name][type] = o
         else
           obj = namespace.children.find {|other| other.name == meth.to_sym && other.scope == scope }

data/lib/yard/handlers/ruby/legacy/visibility_handler.rb

@@ -8,9 +8,10 @@ class YARD::Handlers::Ruby::Legacy::VisibilityHandler < YARD::Handlers::Ruby::Le
     vis = statement.tokens.first.text
     if statement.tokens.size == 1
       self.visibility = vis
+      globals.visibility_origin = :keyword
     else
       tokval_list(statement.tokens[2..-1], :attr).each do |name|
-        MethodObject.new(namespace, name, scope) {|o| o.visibility = vis }
+        MethodObject.new(namespace, name, scope) { |o| o.visibility = vis }
       end
     end
   end

data/lib/yard/handlers/ruby/mixin_handler.rb

@@ -26,22 +26,29 @@ class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
     raise YARD::Parser::UndocumentableError unless mixin.ref?
     raise YARD::Parser::UndocumentableError if mixin.first.type == :ident
 
-    case obj = Proxy.new(namespace, mixin.source)
-    when ConstantObject # If a constant is included, use its value as the real object
-      obj = Proxy.new(namespace, obj.value, :module)
+    if mixin.type == :var_ref && mixin[0] == s(:kw, "self")
+      obj = namespace
     else
-      obj = Proxy.new(namespace, mixin.source, :module)
+      case obj = Proxy.new(namespace, mixin.source)
+      when ConstantObject # If a constant is included, use its value as the real object
+        obj = Proxy.new(namespace, obj.value, :module)
+      else
+        obj = Proxy.new(namespace, mixin.source, :module)
+      end
     end
 
     rec = recipient(mixin)
-    return if rec.nil? || rec.mixins(scope).include?(obj)
+    return if rec.nil?
+
+    ensure_loaded!(rec)
+    return if rec.mixins(scope).include?(obj)
 
     shift = statement.method_name(true) == :include ? :unshift : :push
     rec.mixins(scope).send(shift, obj)
   end
 
   def recipient(mixin)
-    if statement[0].type == :const_path_ref
+    if statement[0].type == :const_path_ref || statement[0].type == :top_const_ref
       Proxy.new(namespace, statement[0].source)
     elsif statement[0].type == :var_ref && statement[0][0] != s(:kw, "self")
       statement[0][0].type == :const ?

data/lib/yard/handlers/ruby/visibility_handler.rb

@@ -13,10 +13,23 @@ class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
     case statement.type
     when :var_ref, :vcall
       self.visibility = ident.first.to_sym
-    when :fcall, :command
+      globals.visibility_origin = :keyword
+    when :command
+      if RUBY_VERSION >= '3.' && is_attribute_method?(statement.parameters.first)
+        parse_block(statement.parameters.first, visibility: ident.first.to_sym)
+        return
+      end
+      process_decorator do |method|
+        method.visibility = ident.first if method.respond_to? :visibility=
+      end
+    when :fcall
       process_decorator do |method|
         method.visibility = ident.first if method.respond_to? :visibility=
       end
     end
   end
+
+  def is_attribute_method?(node)
+    node.type == :command && node.jump(:ident).first.to_s =~ /^attr_(accessor|writer|reader)$/
+  end
 end

data/lib/yard/i18n/locale.rb

@@ -24,7 +24,7 @@ module YARD
 
       # @return [String] the name of the locale. It used IETF language
       #   tag format +[language[_territory][.codeset][@modifier]]+.
-      # @see http://tools.ietf.org/rfc/bcp/bcp47.txt
+      # @see https://tools.ietf.org/rfc/bcp/bcp47.txt
       #   BCP 47 - Tags for Identifying Languages
       attr_reader :name
 
@@ -57,7 +57,7 @@ module YARD
       end
 
       # @param [String] message the translation target message.
-      # @return [String] translated message. If tarnslation isn't
+      # @return [String] translated message. If translation isn't
       #   registered, the +message+ is returned.
       def translate(message)
         @messages[message] || message

data/lib/yard/i18n/message.rb

@@ -8,7 +8,7 @@ module YARD
     #
     # @since 0.8.1
     class Message
-      # @return [String] the message ID of the trnslation target message.
+      # @return [String] the message ID of the translation target message.
       attr_reader :id
 
       # @return [Set] the set of locations. Location is an array of
@@ -18,7 +18,7 @@ module YARD
       # @return [Set] the set of comments for the messages.
       attr_reader :comments
 
-      # Creates a trasnlate target message for message ID +id+.
+      # Creates a translate target message for message ID +id+.
       #
       # @param [String] id the message ID of the translate target message.
       def initialize(id)

data/lib/yard/i18n/messages.rb

@@ -28,7 +28,7 @@ module YARD
         @messages[id]
       end
 
-      # Registers a {Message}, the mssage ID of which is +id+. If
+      # Registers a {Message}, the message ID of which is +id+. If
       # corresponding +Message+ is already registered, the previously
       # registered object is returned.
       #

data/lib/yard/i18n/pot_generator.rb

@@ -60,7 +60,7 @@ module YARD
     #   File.open(po_file_path, "w") do |pot_file|
     #     pot_file.print(pot)
     #   end
-    # @see http://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
+    # @see https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
     #   GNU gettext manual about details of PO file
     class PotGenerator
       # Extracted messages.
@@ -113,7 +113,7 @@ module YARD
       #
       # Locations of the +Message+ are used to generate the reference
       # line that is started with "#: ". +relative_base_path+ passed
-      # when the generater is created is prepended to each path in location.
+      # when the generator is created is prepended to each path in location.
       #
       # Comments of the +Message+ are used to generate the
       # translator-comment line that is started with "# ".