yard 0.9.18 → 0.9.23

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

@@ -1,44 +1,45 @@
-# frozen_string_literal: true
-# Handles alias and alias_method calls
-class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
-  handles :alias, method_call(:alias_method)
-  namespace_only
-
-  process do
-    names = []
-    if statement.type == :alias
-      names = statement.map {|o| o.jump(:ident, :op, :kw, :const).source }
-    elsif statement.call?
-      statement.parameters(false).each do |obj|
-        case obj.type
-        when :symbol_literal, :dyna_symbol
-          names << obj.jump(:ident, :op, :kw, :const).source
-        when :string_literal
-          names << obj.jump(:string_content).source
-        end
-      end
-    end
-    raise YARD::Parser::UndocumentableError, "alias/alias_method" if names.size != 2
-
-    new_meth = names[0].to_sym
-    old_meth = names[1].to_sym
-    old_obj = namespace.child(:name => old_meth, :scope => scope)
-    new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
-      o.add_file(parser.file, statement.line)
-    end
-    namespace.aliases[new_obj] = old_meth
-
-    if old_obj
-      new_obj.signature = old_obj.signature
-      new_obj.source = old_obj.source
-      comments = [old_obj.docstring.to_raw, statement.comments].join("\n")
-      doc = YARD::Docstring.parser.parse(comments, new_obj, self)
-      new_obj.docstring = doc.to_docstring
-      new_obj.docstring.line_range = statement.comments_range
-      new_obj.docstring.hash_flag = statement.comments_hash_flag
-      new_obj.docstring.object = new_obj
-    else
-      new_obj.signature = "def #{new_meth}" # this is all we know.
-    end
-  end
-end
+# frozen_string_literal: true
+# Handles alias and alias_method calls
+class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
+  handles :alias, method_call(:alias_method)
+  namespace_only
+
+  process do
+    names = []
+    if statement.type == :alias
+      nodes = [:ident, :op, :kw, :const, :tstring_content, :string_content]
+      names = statement.map {|o| o.jump(*nodes).source }
+    elsif statement.call?
+      statement.parameters(false).each do |obj|
+        case obj.type
+        when :symbol_literal
+          names << obj.jump(:ident, :op, :kw, :const).source
+        when :string_literal, :dyna_symbol
+          names << obj.jump(:string_content, :tstring_content).source
+        end
+      end
+    end
+    raise YARD::Parser::UndocumentableError, "alias/alias_method" if names.size != 2
+
+    new_meth = names[0].to_sym
+    old_meth = names[1].to_sym
+    old_obj = namespace.child(:name => old_meth, :scope => scope)
+    new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
+      o.add_file(parser.file, statement.line)
+    end
+    namespace.aliases[new_obj] = old_meth
+
+    if old_obj
+      new_obj.signature = old_obj.signature
+      new_obj.source = old_obj.source
+      comments = [old_obj.docstring.to_raw, statement.comments].join("\n")
+      doc = YARD::Docstring.parser.parse(comments, new_obj, self)
+      new_obj.docstring = doc.to_docstring
+      new_obj.docstring.line_range = statement.comments_range
+      new_obj.docstring.hash_flag = statement.comments_hash_flag
+      new_obj.docstring.object = new_obj
+    else
+      new_obj.signature = "def #{new_meth}" # this is all we know.
+    end
+  end
+end

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

@@ -1,87 +1,87 @@
-# frozen_string_literal: true
-# Handles +attr_*+ statements in modules/classes
-class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
-  handles method_call(:attr)
-  handles method_call(:attr_reader)
-  handles method_call(:attr_writer)
-  handles method_call(:attr_accessor)
-  namespace_only
-
-  process do
-    return if statement.type == :var_ref || statement.type == :vcall
-    read = true
-    write = false
-    params = statement.parameters(false).dup
-
-    # Change read/write based on attr_reader/writer/accessor
-    case statement.method_name(true)
-    when :attr
-      # In the case of 'attr', the second parameter (if given) isn't a symbol.
-      if params.size == 2
-        write = true if params.pop == s(:var_ref, s(:kw, "true"))
-      end
-    when :attr_accessor
-      write = true
-    when :attr_reader
-      # change nothing
-    when :attr_writer
-      read = false
-      write = true
-    end
-
-    # 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
-          o = MethodObject.new(namespace, meth, scope)
-          if type == :write
-            o.parameters = [['value', nil]]
-            src = "def #{meth}(value)"
-            full_src = "#{src}\n  @#{name} = value\nend"
-            doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
-          else
-            src = "def #{meth}"
-            full_src = "#{src}\n  @#{name}\nend"
-            doc = "Returns the value of attribute #{name}"
-          end
-          o.source ||= full_src
-          o.signature ||= src
-          register(o)
-          o.docstring = doc if o.docstring.blank?(false)
-
-          # Regsiter the object explicitly
-          namespace.attributes[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][type] = obj if obj
-        end
-      end
-    end
-  end
-
-  protected
-
-  # Strips out any non-essential arguments from the attr statement.
-  #
-  # @param [Array<Parser::Ruby::AstNode>] params a list of the parameters
-  #   in the attr call.
-  # @return [Array<String>] the validated attribute names
-  # @raise [Parser::UndocumentableError] if the arguments are not valid.
-  def validated_attribute_names(params)
-    params.map do |obj|
-      case obj.type
-      when :symbol_literal
-        obj.jump(:ident, :op, :kw, :const).source
-      when :string_literal
-        obj.jump(:string_content).source
-      else
-        raise YARD::Parser::UndocumentableError, obj.source
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+# Handles +attr_*+ statements in modules/classes
+class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:attr)
+  handles method_call(:attr_reader)
+  handles method_call(:attr_writer)
+  handles method_call(:attr_accessor)
+  namespace_only
+
+  process do
+    return if statement.type == :var_ref || statement.type == :vcall
+    read = true
+    write = false
+    params = statement.parameters(false).dup
+
+    # Change read/write based on attr_reader/writer/accessor
+    case statement.method_name(true)
+    when :attr
+      # In the case of 'attr', the second parameter (if given) isn't a symbol.
+      if params.size == 2
+        write = true if params.pop == s(:var_ref, s(:kw, "true"))
+      end
+    when :attr_accessor
+      write = true
+    when :attr_reader
+      # change nothing
+    when :attr_writer
+      read = false
+      write = true
+    end
+
+    # 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
+          o = MethodObject.new(namespace, meth, scope)
+          if type == :write
+            o.parameters = [['value', nil]]
+            src = "def #{meth}(value)"
+            full_src = "#{src}\n  @#{name} = value\nend"
+            doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
+          else
+            src = "def #{meth}"
+            full_src = "#{src}\n  @#{name}\nend"
+            doc = "Returns the value of attribute #{name}."
+          end
+          o.source ||= full_src
+          o.signature ||= src
+          register(o)
+          o.docstring = doc if o.docstring.blank?(false)
+
+          # Regsiter the object explicitly
+          namespace.attributes[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][type] = obj if obj
+        end
+      end
+    end
+  end
+
+  protected
+
+  # Strips out any non-essential arguments from the attr statement.
+  #
+  # @param [Array<Parser::Ruby::AstNode>] params a list of the parameters
+  #   in the attr call.
+  # @return [Array<String>] the validated attribute names
+  # @raise [Parser::UndocumentableError] if the arguments are not valid.
+  def validated_attribute_names(params)
+    params.map do |obj|
+      case obj.type
+      when :symbol_literal
+        obj.jump(:ident, :op, :kw, :const).source
+      when :string_literal
+        obj.jump(:string_content).source
+      else
+        raise YARD::Parser::UndocumentableError, obj.source
+      end
+    end
+  end
+end

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

@@ -1,165 +1,165 @@
-# frozen_string_literal: true
-module YARD
-  module Handlers
-    module Ruby
-      # To implement a custom handler matcher, subclass this class and implement
-      # {#matches?} to return whether a node matches the handler.
-      #
-      # @example A Custom Handler Matcher Extension
-      #   # Implements a handler that checks for a specific string
-      #   # in the node's source.
-      #   class MyExtension < HandlesExtension
-      #     def matches?(node) node.source.include?(name) end
-      #   end
-      #
-      #   # This handler will handle any node where the source includes 'foo'
-      #   class MyHandler < Handlers::Ruby::Base
-      #     handles MyExtension.new('foo')
-      #   end
-      class HandlesExtension
-        # Creates a new extension with a specific matcher value +name+
-        # @param [Object] name the matcher value to check against {#matches?}
-        def initialize(name) @name = name end
-
-        # Tests if the node matches the handler
-        # @param [Parser::Ruby::AstNode] node a Ruby node
-        # @return [Boolean] whether the +node+ matches the handler
-        def matches?(node) # rubocop:disable Lint/UnusedMethodArgument
-          raise NotImplementedError
-        end
-
-        protected
-
-        # @return [String] the extension matcher value
-        attr_reader :name
-      end
-
-      class MethodCallWrapper < HandlesExtension
-        def matches?(node)
-          case node.type
-          when :var_ref
-            if !node.parent || node.parent.type == :list
-              return true if node[0].type == :ident && (name.nil? || node[0][0] == name)
-            end
-          when :fcall, :command, :vcall
-            return true if name.nil? || node[0][0] == name
-          when :call, :command_call
-            return true if name.nil? || node[2][0] == name
-          end
-          false
-        end
-      end
-
-      class TestNodeWrapper < HandlesExtension
-        def matches?(node) !node.send(name).is_a?(FalseClass) end
-      end
-
-      # This is the base handler class for the new-style (1.9) Ruby parser.
-      # All handlers that subclass this base class will be used when the
-      # new-style parser is used. For implementing legacy handlers, see
-      # {Legacy::Base}.
-      #
-      # @abstract See {Handlers::Base} for subclassing information.
-      # @see Handlers::Base
-      # @see Legacy::Base
-      class Base < Handlers::Base
-        class << self
-          include Parser::Ruby
-
-          # @group Statement Matcher Extensions
-
-          # Matcher for handling any type of method call. Method calls can
-          # be expressed by many {AstNode} types depending on the syntax
-          # with which it is called, so YARD allows you to use this matcher
-          # to simplify matching a method call.
-          #
-          # @example Match the "describe" method call
-          #   handles method_call(:describe)
-          #
-          #   # The following will be matched:
-          #   # describe(...)
-          #   # object.describe(...)
-          #   # describe "argument" do ... end
-          #
-          # @param [#to_s] name matches the method call of this name
-          # @return [void]
-          def method_call(name = nil)
-            MethodCallWrapper.new(name ? name.to_s : nil)
-          end
-
-          # Matcher for handling a node with a specific meta-type. An {AstNode}
-          # has a {AstNode#type} to define its type but can also be associated
-          # with a set of types. For instance, +:if+ and +:unless+ are both
-          # of the meta-type +:condition+.
-          #
-          # A meta-type is any method on the {AstNode} class ending in "?",
-          # though you should not include the "?" suffix in your declaration.
-          # Some examples are: "condition", "call", "literal", "kw", "token",
-          # "ref".
-          #
-          # @example Handling any conditional statement (if, unless)
-          #   handles meta_type(:condition)
-          # @param [Symbol] type the meta-type to match. A meta-type can be
-          #   any method name + "?" that {AstNode} responds to.
-          # @return [void]
-          def meta_type(type)
-            TestNodeWrapper.new(type.to_s + "?")
-          end
-
-          # @group Testing for a Handler
-
-          # @return [Boolean] whether or not an {AstNode} object should be
-          #   handled by this handler
-          def handles?(node)
-            handlers.any? do |a_handler|
-              case a_handler
-              when Symbol
-                a_handler == node.type
-              when String
-                node.source == a_handler
-              when Regexp
-                node.source =~ a_handler
-              when Parser::Ruby::AstNode
-                a_handler == node
-              when HandlesExtension
-                a_handler.matches?(node)
-              end
-            end
-          end
-        end
-
-        include Parser::Ruby
-
-        # @group Parsing an Inner Block
-
-        def parse_block(inner_node, opts = {})
-          push_state(opts) do
-            nodes = inner_node.type == :list ? inner_node.children : [inner_node]
-            parser.process(nodes)
-          end
-        end
-
-        # @group Macro Handling
-
-        def call_params
-          return [] unless statement.respond_to?(:parameters)
-          statement.parameters(false).compact.map do |param|
-            if param.type == :list
-              param.map {|n| n.jump(:ident, :kw, :tstring_content).source }
-            else
-              param.jump(:ident, :kw, :tstring_content).source
-            end
-          end.flatten
-        end
-
-        def caller_method
-          if statement.call? || statement.def?
-            statement.method_name(true).to_s
-          elsif statement.type == :var_ref || statement.type == :vcall
-            statement[0].jump(:ident, :kw).source
-          end
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  module Handlers
+    module Ruby
+      # To implement a custom handler matcher, subclass this class and implement
+      # {#matches?} to return whether a node matches the handler.
+      #
+      # @example A Custom Handler Matcher Extension
+      #   # Implements a handler that checks for a specific string
+      #   # in the node's source.
+      #   class MyExtension < HandlesExtension
+      #     def matches?(node) node.source.include?(name) end
+      #   end
+      #
+      #   # This handler will handle any node where the source includes 'foo'
+      #   class MyHandler < Handlers::Ruby::Base
+      #     handles MyExtension.new('foo')
+      #   end
+      class HandlesExtension
+        # Creates a new extension with a specific matcher value +name+
+        # @param [Object] name the matcher value to check against {#matches?}
+        def initialize(name) @name = name end
+
+        # Tests if the node matches the handler
+        # @param [Parser::Ruby::AstNode] node a Ruby node
+        # @return [Boolean] whether the +node+ matches the handler
+        def matches?(node) # rubocop:disable Lint/UnusedMethodArgument
+          raise NotImplementedError
+        end
+
+        protected
+
+        # @return [String] the extension matcher value
+        attr_reader :name
+      end
+
+      class MethodCallWrapper < HandlesExtension
+        def matches?(node)
+          case node.type
+          when :var_ref
+            if !node.parent || node.parent.type == :list
+              return true if node[0].type == :ident && (name.nil? || node[0][0] == name)
+            end
+          when :fcall, :command, :vcall
+            return true if name.nil? || node[0][0] == name
+          when :call, :command_call
+            return true if name.nil? || node[2][0] == name
+          end
+          false
+        end
+      end
+
+      class TestNodeWrapper < HandlesExtension
+        def matches?(node) !node.send(name).is_a?(FalseClass) end
+      end
+
+      # This is the base handler class for the new-style (1.9) Ruby parser.
+      # All handlers that subclass this base class will be used when the
+      # new-style parser is used. For implementing legacy handlers, see
+      # {Legacy::Base}.
+      #
+      # @abstract See {Handlers::Base} for subclassing information.
+      # @see Handlers::Base
+      # @see Legacy::Base
+      class Base < Handlers::Base
+        class << self
+          include Parser::Ruby
+
+          # @group Statement Matcher Extensions
+
+          # Matcher for handling any type of method call. Method calls can
+          # be expressed by many {AstNode} types depending on the syntax
+          # with which it is called, so YARD allows you to use this matcher
+          # to simplify matching a method call.
+          #
+          # @example Match the "describe" method call
+          #   handles method_call(:describe)
+          #
+          #   # The following will be matched:
+          #   # describe(...)
+          #   # object.describe(...)
+          #   # describe "argument" do ... end
+          #
+          # @param [#to_s] name matches the method call of this name
+          # @return [void]
+          def method_call(name = nil)
+            MethodCallWrapper.new(name ? name.to_s : nil)
+          end
+
+          # Matcher for handling a node with a specific meta-type. An {AstNode}
+          # has a {AstNode#type} to define its type but can also be associated
+          # with a set of types. For instance, +:if+ and +:unless+ are both
+          # of the meta-type +:condition+.
+          #
+          # A meta-type is any method on the {AstNode} class ending in "?",
+          # though you should not include the "?" suffix in your declaration.
+          # Some examples are: "condition", "call", "literal", "kw", "token",
+          # "ref".
+          #
+          # @example Handling any conditional statement (if, unless)
+          #   handles meta_type(:condition)
+          # @param [Symbol] type the meta-type to match. A meta-type can be
+          #   any method name + "?" that {AstNode} responds to.
+          # @return [void]
+          def meta_type(type)
+            TestNodeWrapper.new(type.to_s + "?")
+          end
+
+          # @group Testing for a Handler
+
+          # @return [Boolean] whether or not an {AstNode} object should be
+          #   handled by this handler
+          def handles?(node)
+            handlers.any? do |a_handler|
+              case a_handler
+              when Symbol
+                a_handler == node.type
+              when String
+                node.source == a_handler
+              when Regexp
+                node.source =~ a_handler
+              when Parser::Ruby::AstNode
+                a_handler == node
+              when HandlesExtension
+                a_handler.matches?(node)
+              end
+            end
+          end
+        end
+
+        include Parser::Ruby
+
+        # @group Parsing an Inner Block
+
+        def parse_block(inner_node, opts = {})
+          push_state(opts) do
+            nodes = inner_node.type == :list ? inner_node.children : [inner_node]
+            parser.process(nodes)
+          end
+        end
+
+        # @group Macro Handling
+
+        def call_params
+          return [] unless statement.respond_to?(:parameters)
+          statement.parameters(false).compact.map do |param|
+            if param.type == :list
+              param.map {|n| n.jump(:ident, :kw, :tstring_content).source }
+            else
+              param.jump(:ident, :kw, :tstring_content).source
+            end
+          end.flatten
+        end
+
+        def caller_method
+          if statement.call? || statement.def?
+            statement.method_name(true).to_s
+          elsif statement.type == :var_ref || statement.type == :vcall
+            statement[0].jump(:ident, :kw).source
+          end
+        end
+      end
+    end
+  end
+end