yard 0.9.36 → 0.9.43

data/lib/yard/cli/diff.rb

@@ -2,6 +2,7 @@
 require 'tmpdir'
 require 'fileutils'
 require 'open-uri'
+require 'open3'
 
 module YARD
   module CLI
@@ -108,7 +109,11 @@ module YARD
         FileUtils.mkdir_p(tmpdir)
         FileUtils.cp_r('.', tmpdir)
         Dir.chdir(tmpdir)
-        log.info("git says: " + `git reset --hard #{commit}`.chomp)
+        out, status = Open3.capture2e('git', 'reset', '--hard', commit)
+        log.info("git says: " + out.chomp)
+        unless status.success?
+          raise "git reset --hard #{commit.inspect} failed with exit status #{status.exitstatus}: #{out}"
+        end
         generate_yardoc(tmpdir)
       ensure
         Dir.chdir(@old_path)
@@ -158,7 +163,7 @@ module YARD
         end
 
         # Remote gemfile from rubygems.org
-        url = "http://rubygems.org/downloads/#{gemfile}"
+        url = "https://rubygems.org/downloads/#{gemfile}"
         log.info "Searching for remote gem file #{url}"
         begin
           # Note: In Ruby 2.4.x, URI.open is a private method. After

data/lib/yard/code_objects/base.rb

@@ -228,7 +228,7 @@ module YARD
       # @example Create class Z inside namespace X::Y
       #   CodeObjects::Base.new(P("X::Y"), :Z) # or
       #   CodeObjects::Base.new(Registry.root, "X::Y")
-      # @param [NamespaceObject] namespace the namespace the object belongs in,
+      # @param [NamespaceObject, :root, nil] namespace the namespace the object belongs in,
       #   {Registry.root} or :root should be provided if it is associated with
       #   the top level namespace.
       # @param [Symbol, String] name the name (or complex path) of the object.

data/lib/yard/code_objects/extra_file_object.rb

@@ -127,6 +127,7 @@ module YARD::CodeObjects
     end
 
     def translate(data)
+      return data if locale.nil?
       text = YARD::I18n::Text.new(data, :have_header => true)
       text.translate(YARD::Registry.locale(locale))
     end

data/lib/yard/code_objects/macro_object.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-require 'ostruct'
 
 module YARD
   module CodeObjects

data/lib/yard/code_objects/proxy.rb

@@ -201,7 +201,7 @@ module YARD
 
       private
 
-      # @note this method fixes a bug in 1.9.2: http://gist.github.com/437136
+      # @note this method fixes a bug in 1.9.2: https://gist.github.com/437136
       def to_ary; nil end
 
       # Attempts to find the object that this unresolved object

data/lib/yard/docstring_parser.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-require 'ostruct'
 
 module YARD
   # Parses text and creates a {Docstring} object to represent documentation

data/lib/yard/handlers/base.rb

@@ -462,6 +462,18 @@ module YARD
           end
         end
 
+        if docstring.is_a?(String)
+          if (m = docstring.match(/^\s*@!?visibility\s+(public|private|protected)\b/m))
+            vis_sym = m[1].to_sym
+
+            if object.nil?
+              globals.visibility_origin = :directive
+            elsif object.is_a?(CodeObjects::MethodObject)
+              object.visibility = vis_sym
+            end
+          end
+        end
+
         register_transitive_tags(object)
       end
 
@@ -511,7 +523,17 @@ module YARD
       def register_visibility(object, visibility = self.visibility)
         return unless object.respond_to?(:visibility=)
         return if object.is_a?(NamespaceObject)
-        object.visibility = visibility
+
+        if object.is_a?(CodeObjects::MethodObject)
+          origin = globals.visibility_origin
+          if origin == :keyword
+            object.visibility = visibility if object.scope == scope
+          else
+            object.visibility = visibility
+          end
+        else
+          object.visibility = visibility
+        end
       end
 
       # Registers the same method information on the module function, if

data/lib/yard/handlers/processor.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-require 'ostruct'
 
 module YARD
   module Handlers
@@ -36,6 +35,7 @@ module YARD
       register_handler_namespace :ruby, Ruby
       register_handler_namespace :ruby18, Ruby::Legacy
       register_handler_namespace :c, C
+      register_handler_namespace :rbs, RBS
 
       # @return [String] the filename
       attr_accessor :file

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# Handles RBS attr_reader, attr_writer, and attr_accessor declarations.
+#
+# Registers one or two {YARD::CodeObjects::MethodObject} instances (reader
+# and/or writer) with @return / @param tags derived from the RBS type.
+class YARD::Handlers::RBS::AttributeHandler < YARD::Handlers::RBS::Base
+  handles :attr_reader, :attr_writer, :attr_accessor
+
+  process do
+    attr_name  = statement.name
+    rbs_type   = statement.attr_rbs_type
+    yard_types = rbs_type ? YARD::Handlers::RBS::MethodHandler.rbs_type_to_yard_types(rbs_type) : nil
+    mscope     = statement.visibility == :class ? :class : :instance
+
+    case statement.type
+    when :attr_reader
+      register_reader(attr_name, yard_types, mscope)
+      register_existing_attribute_method(attr_name, "#{attr_name}=", :write, mscope)
+    when :attr_writer
+      register_existing_attribute_method(attr_name, attr_name, :read, mscope)
+      register_writer(attr_name, yard_types, mscope)
+    when :attr_accessor
+      register_reader(attr_name, yard_types, mscope)
+      register_writer(attr_name, yard_types, mscope)
+    end
+  end
+
+  private
+
+  def register_reader(name, types, scope)
+    obj = MethodObject.new(namespace, name, scope)
+    obj.source ||= "def #{name}\n  @#{name}\nend"
+    obj.signature ||= "def #{name}"
+    obj = register(obj)
+    obj.docstring = "Returns the value of attribute #{name}." if obj.docstring.blank?(false)
+    apply_tag_types(obj, :return, types)
+    namespace.attributes[obj.scope][name] ||= SymbolHash[:read => nil, :write => nil]
+    namespace.attributes[obj.scope][name][:read] = obj
+    obj
+  end
+
+  def register_writer(name, types, scope)
+    obj = MethodObject.new(namespace, "#{name}=", scope)
+    obj.parameters = [['value', nil]]
+    obj.source ||= "def #{name}=(value)\n  @#{name} = value\nend"
+    obj.signature ||= "def #{name}=(value)"
+    obj = register(obj)
+    obj.docstring = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to." if obj.docstring.blank?(false)
+    apply_tag_types(obj, :param, types, "value")
+    namespace.attributes[obj.scope][name] ||= SymbolHash[:read => nil, :write => nil]
+    namespace.attributes[obj.scope][name][:write] = obj
+    obj
+  end
+
+  def register_existing_attribute_method(attr_name, meth_name, type, scope)
+    namespace.attributes[scope][attr_name] ||= SymbolHash[:read => nil, :write => nil]
+    return if namespace.attributes[scope][attr_name][type]
+
+    obj = namespace.children.find do |other|
+      other.name == meth_name.to_sym && other.scope == scope
+    end
+
+    namespace.attributes[scope][attr_name][type] = obj if obj
+  end
+
+  def apply_tag_types(obj, tag_name, types, tag_param_name = nil)
+    return unless types
+
+    tag = obj.tags(tag_name).find do |existing_tag|
+      existing_tag.name == tag_param_name
+    end
+
+    if tag
+      tag.types ||= types
+    else
+      obj.add_tag YARD::Tags::Tag.new(tag_name, '', types, tag_param_name)
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+module YARD
+  module Handlers
+    # Handlers for RBS (Ruby type signature) files.
+    module RBS
+      # Base class for all RBS handlers.
+      # Handlers match on the {Parser::RBS::Statement#type} symbol of the
+      # current statement and process it to create or annotate code objects.
+      class Base < Handlers::Base
+        # @return [Boolean] whether this handler matches the given statement
+        def self.handles?(statement, _processor)
+          handlers.any? do |matcher|
+            case matcher
+            when Symbol
+              statement.type == matcher
+            when String
+              statement.type.to_s == matcher
+            when Regexp
+              (statement.source || '') =~ matcher
+            else
+              false
+            end
+          end
+        end
+
+        # Recurse into the body of a namespace statement.
+        # @param opts [Hash] state overrides
+        # @see #push_state
+        def parse_block(opts = {})
+          return if statement.block.nil? || statement.block.empty?
+          push_state(opts) do
+            parser.process(statement.block)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# Handles RBS constant declarations: `Name: Type`
+class YARD::Handlers::RBS::ConstantHandler < YARD::Handlers::RBS::Base
+  handles :constant
+
+  process do
+    obj = register ConstantObject.new(namespace, statement.name)
+    if statement.attr_rbs_type && !obj.has_tag?(:return)
+      obj.add_tag YARD::Tags::Tag.new(:return, '', rbs_types(statement.attr_rbs_type))
+    end
+  end
+
+  private
+
+  def rbs_types(type_str)
+    YARD::Handlers::RBS::MethodHandler.rbs_type_to_yard_types(type_str)
+  end
+end

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)
 
-          # Register 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