yard 0.9.16 → 0.9.17

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

@@ -1,10 +1,10 @@
-# frozen_string_literal: true
-# Handles any lone comment statement in a Ruby file
-class YARD::Handlers::Ruby::CommentHandler < YARD::Handlers::Ruby::Base
-  handles :comment, :void_stmt
-  namespace_only
-
-  process do
-    register_docstring(nil)
-  end
-end
+# frozen_string_literal: true
+# Handles any lone comment statement in a Ruby file
+class YARD::Handlers::Ruby::CommentHandler < YARD::Handlers::Ruby::Base
+  handles :comment, :void_stmt
+  namespace_only
+
+  process do
+    register_docstring(nil)
+  end
+end

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

@@ -1,59 +1,59 @@
-# frozen_string_literal: true
-# Handles any constant assignment
-class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
-  include YARD::Handlers::Ruby::StructHandlerMethods
-  handles :assign
-  namespace_only
-
-  process do
-    if statement[1].call? && statement[1][0][0] == s(:const, "Struct") &&
-       statement[1][2] == s(:ident, "new")
-      process_structclass(statement)
-    elsif statement[0].type == :var_field && statement[0][0].type == :const
-      process_constant(statement)
-    elsif statement[0].type == :const_path_field
-      process_constant(statement)
-    end
-  end
-
-  private
-
-  def process_constant(statement)
-    name = statement[0].source
-    value = if statement[1].type == :dyna_symbol
-              statement[1].first.source.intern.inspect
-            else
-              statement[1].source
-            end
-    obj = P(namespace, name)
-    if obj.is_a?(NamespaceObject) && obj.namespace == namespace
-      raise YARD::Parser::UndocumentableError, "constant for existing #{obj.type} #{obj}"
-    else
-      ensure_loaded! obj.parent
-      register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
-    end
-  end
-
-  def process_structclass(statement)
-    lhs = statement[0][0]
-    if lhs.type == :const
-      klass = create_class(lhs[0], 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}"
-    end
-  end
-
-  # Extract the parameters from the Struct.new AST node, returning them as a list
-  # of strings
-  #
-  # @param [MethodCallNode] superclass the AST node for the Struct.new call
-  # @return [Array<String>] the member names to generate methods for
-  def extract_parameters(superclass)
-    return [] unless superclass.parameters
-    members = superclass.parameters.select {|x| x && x.type == :symbol_literal }
-    members.map! {|x| x.source.strip[1..-1] }
-    members
-  end
-end
+# frozen_string_literal: true
+# Handles any constant assignment
+class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
+  include YARD::Handlers::Ruby::StructHandlerMethods
+  handles :assign
+  namespace_only
+
+  process do
+    if statement[1].call? && statement[1][0][0] == s(:const, "Struct") &&
+       statement[1][2] == s(:ident, "new")
+      process_structclass(statement)
+    elsif statement[0].type == :var_field && statement[0][0].type == :const
+      process_constant(statement)
+    elsif statement[0].type == :const_path_field
+      process_constant(statement)
+    end
+  end
+
+  private
+
+  def process_constant(statement)
+    name = statement[0].source
+    value = if statement[1].type == :dyna_symbol
+              statement[1].first.source.intern.inspect
+            else
+              statement[1].source
+            end
+    obj = P(namespace, name)
+    if obj.is_a?(NamespaceObject) && obj.namespace == namespace
+      raise YARD::Parser::UndocumentableError, "constant for existing #{obj.type} #{obj}"
+    else
+      ensure_loaded! obj.parent
+      register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
+    end
+  end
+
+  def process_structclass(statement)
+    lhs = statement[0][0]
+    if lhs.type == :const
+      klass = create_class(lhs[0], 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}"
+    end
+  end
+
+  # Extract the parameters from the Struct.new AST node, returning them as a list
+  # of strings
+  #
+  # @param [MethodCallNode] superclass the AST node for the Struct.new call
+  # @return [Array<String>] the member names to generate methods for
+  def extract_parameters(superclass)
+    return [] unless superclass.parameters
+    members = superclass.parameters.select {|x| x && x.type == :symbol_literal }
+    members.map! {|x| x.source.strip[1..-1] }
+    members
+  end
+end

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

@@ -1,123 +1,123 @@
-# frozen_string_literal: true
-# Helper methods to assist with processing decorators.
-module YARD::Handlers::Ruby::DecoratorHandlerMethods
-  # @overload process_decorator(*nodes, opts = {}, &block)
-  #   Takes care of parsing method definitions passed to decorators
-  #   as parameters, as well as parsing chained decorators.
-  #
-  #   Use this in a handler's process block.
-  #
-  #   @yieldparam method [YARD::CodeObjects::MethodObject] Method being decorated.
-  #   @yieldparam node [YARD::Parser::Ruby::AstNode] AST node of the decorated method.
-  #   @yieldparam name [Symbol] Name of the decorated method.
-  #   @return [Array<Hash>] Array of hashes containing :method, :node, :name.
-  #     See yield params.
-  #
-  #   @param nodes [YARD::Parser::Ruby::AstNode] AST nodes that refer to decorated
-  #     methods, like indexes of statement.parameter. Defaults to all parameters.
-  #     Pass nil to specify zero parameters.
-  #
-  #   @option opts [:instance, :class] :scope (:instance) Scope to use for each
-  #     MethodObject.
-  #
-  #   @option opts [true, false] :transfer_docstring Set false to disable
-  #     transferring the decorator docstring to method definitions passed to the
-  #     decorator as parameters.
-  #
-  #   @option opts [true, false] :transfer_source Set false to disable
-  #     transferring the decorator source code string to method definitions
-  #     passed to the decorator as parameters.
-  #
-  #   @example Basic Usage
-  #     # Simply pass the method docs through to the method definition.
-  #     process do
-  #       process_decorator
-  #     end
-  #
-  #   @example Setting a method's visibility to private.
-  #     process do
-  #       process_decorator :scope => :class do |method|
-  #         method.visibility = :private if method.respond_to? :visibility
-  #       end
-  #     end
-  def process_decorator(*nodes, &block)
-    opts = nodes.last.is_a?(Hash) ? nodes.pop : {}
-
-    all_nodes = statement.parameters.select do |p|
-      p.is_a? YARD::Parser::Ruby::AstNode
-    end
-
-    # Parse decorator parameters (decorator chain).
-    all_nodes.each do |param|
-      parse_block param if param.call? || param.def?
-    end
-
-    selected_nodes =
-      if nodes.empty?
-        all_nodes
-      elsif nodes.count == 1 && nodes.first.nil?
-        []
-      else
-        nodes
-      end
-
-    decorated_methods = selected_nodes.map do |param|
-      process_decorator_parameter param, opts, &block
-    end.flatten
-
-    # Store method nodes in decorator node.
-    statement.define_singleton_method :decorators do
-      decorated_methods.map {|h| h[:node] }
-    end
-
-    decorated_methods
-  end
-
-  private
-
-  def process_decorator_parameter(node, opts = {}, &block)
-    scope              = opts.fetch :scope, :instance
-    transfer_docstring = opts.fetch :transfer_docstring, true
-    transfer_source    = opts.fetch :transfer_source, true
-
-    name = nil
-
-    if node.call?
-      if node.respond_to? :decorators
-        return node.decorators.map do |n|
-          process_decorator_parameter n, opts, &block
-        end
-      end
-    elsif node.def?
-      name = node.jump(:def).method_name.source
-    else
-      name = node.jump(:ident, :string_content, :const).source
-    end
-
-    if name.nil?
-      raise YARD::Parser::UndocumentableError, 'statement, cannot determine method name'
-    end
-
-    method = YARD::CodeObjects::Proxy.new(
-      namespace,
-      (scope == :instance ? '#' : '.') + name.to_s,
-      :method
-    )
-
-    # Transfer source to methods passed to the helper as parameters.
-    method.source = statement.source if transfer_source && node.def?
-
-    # Transfer decorator docstring to methods passed to the helper as parameters.
-    if transfer_docstring && node.def? &&
-       statement.docstring && method.docstring.empty?
-      tags = method.tags if method.respond_to? :tags
-      tags ||= []
-      method.docstring = statement.docstring
-      tags.each {|t| method.add_tag t }
-    end
-
-    yield method, node, name.to_sym if block_given?
-
-    [{:method => method, :node => node, :name => name.to_sym}]
-  end
-end
+# frozen_string_literal: true
+# Helper methods to assist with processing decorators.
+module YARD::Handlers::Ruby::DecoratorHandlerMethods
+  # @overload process_decorator(*nodes, opts = {}, &block)
+  #   Takes care of parsing method definitions passed to decorators
+  #   as parameters, as well as parsing chained decorators.
+  #
+  #   Use this in a handler's process block.
+  #
+  #   @yieldparam method [YARD::CodeObjects::MethodObject] Method being decorated.
+  #   @yieldparam node [YARD::Parser::Ruby::AstNode] AST node of the decorated method.
+  #   @yieldparam name [Symbol] Name of the decorated method.
+  #   @return [Array<Hash>] Array of hashes containing :method, :node, :name.
+  #     See yield params.
+  #
+  #   @param nodes [YARD::Parser::Ruby::AstNode] AST nodes that refer to decorated
+  #     methods, like indexes of statement.parameter. Defaults to all parameters.
+  #     Pass nil to specify zero parameters.
+  #
+  #   @option opts [:instance, :class] :scope (:instance) Scope to use for each
+  #     MethodObject.
+  #
+  #   @option opts [true, false] :transfer_docstring Set false to disable
+  #     transferring the decorator docstring to method definitions passed to the
+  #     decorator as parameters.
+  #
+  #   @option opts [true, false] :transfer_source Set false to disable
+  #     transferring the decorator source code string to method definitions
+  #     passed to the decorator as parameters.
+  #
+  #   @example Basic Usage
+  #     # Simply pass the method docs through to the method definition.
+  #     process do
+  #       process_decorator
+  #     end
+  #
+  #   @example Setting a method's visibility to private.
+  #     process do
+  #       process_decorator :scope => :class do |method|
+  #         method.visibility = :private if method.respond_to? :visibility
+  #       end
+  #     end
+  def process_decorator(*nodes, &block)
+    opts = nodes.last.is_a?(Hash) ? nodes.pop : {}
+
+    all_nodes = statement.parameters.select do |p|
+      p.is_a? YARD::Parser::Ruby::AstNode
+    end
+
+    # Parse decorator parameters (decorator chain).
+    all_nodes.each do |param|
+      parse_block param if param.call? || param.def?
+    end
+
+    selected_nodes =
+      if nodes.empty?
+        all_nodes
+      elsif nodes.count == 1 && nodes.first.nil?
+        []
+      else
+        nodes
+      end
+
+    decorated_methods = selected_nodes.map do |param|
+      process_decorator_parameter param, opts, &block
+    end.flatten
+
+    # Store method nodes in decorator node.
+    statement.define_singleton_method :decorators do
+      decorated_methods.map {|h| h[:node] }
+    end
+
+    decorated_methods
+  end
+
+  private
+
+  def process_decorator_parameter(node, opts = {}, &block)
+    scope              = opts.fetch :scope, :instance
+    transfer_docstring = opts.fetch :transfer_docstring, true
+    transfer_source    = opts.fetch :transfer_source, true
+
+    name = nil
+
+    if node.call?
+      if node.respond_to? :decorators
+        return node.decorators.map do |n|
+          process_decorator_parameter n, opts, &block
+        end
+      end
+    elsif node.def?
+      name = node.jump(:def).method_name.source
+    else
+      name = node.jump(:ident, :string_content, :const).source
+    end
+
+    if name.nil?
+      raise YARD::Parser::UndocumentableError, 'statement, cannot determine method name'
+    end
+
+    method = YARD::CodeObjects::Proxy.new(
+      namespace,
+      (scope == :instance ? '#' : '.') + name.to_s,
+      :method
+    )
+
+    # Transfer source to methods passed to the helper as parameters.
+    method.source = statement.source if transfer_source && node.def?
+
+    # Transfer decorator docstring to methods passed to the helper as parameters.
+    if transfer_docstring && node.def? &&
+       statement.docstring && method.docstring.empty?
+      tags = method.tags if method.respond_to? :tags
+      tags ||= []
+      method.docstring = statement.docstring
+      tags.each {|t| method.add_tag t }
+    end
+
+    yield method, node, name.to_sym if block_given?
+
+    [{:method => method, :node => node, :name => name.to_sym}]
+  end
+end

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

@@ -1,15 +1,15 @@
-# frozen_string_literal: true
-module YARD
-  module Handlers
-    module Ruby
-      # Handles automatic detection of dsl-style methods
-      class DSLHandler < Base
-        include CodeObjects
-        include DSLHandlerMethods
-        handles method_call
-        namespace_only
-        process { handle_comments }
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  module Handlers
+    module Ruby
+      # Handles automatic detection of dsl-style methods
+      class DSLHandler < Base
+        include CodeObjects
+        include DSLHandlerMethods
+        handles method_call
+        namespace_only
+        process { handle_comments }
+      end
+    end
+  end
+end

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

@@ -1,95 +1,96 @@
-# frozen_string_literal: true
-module YARD
-  module Handlers
-    module Ruby
-      module DSLHandlerMethods
-        include CodeObjects
-        include Parser
-
-        IGNORE_METHODS = Hash[*%w(alias alias_method autoload attr attr_accessor
-          attr_reader attr_writer extend include public private protected
-          private_constant).map {|n| [n, true] }.flatten]
-
-        def handle_comments
-          return if IGNORE_METHODS[caller_method]
-
-          @docstring = statement.comments || ""
-          @docstring = @docstring.join("\n") if @docstring.is_a?(Array)
-
-          attaching = false
-          if @docstring =~ /^@!?macro\s+\[[^\]]*attach/
-            register_docstring(nil)
-            @docstring = ""
-            attaching = true
-          end
-
-          macro = find_attached_macro
-          if macro
-            txt = macro.expand([caller_method, *call_params], statement.source)
-            @docstring += "\n" + txt
-
-            # macro may have a directive
-            return register_docstring(nil) if !attaching && txt.match(/^\s*@!/)
-          elsif !statement.comments_hash_flag && !implicit_docstring?
-            return register_docstring(nil)
-          end
-
-          # ignore DSL definitions if @method/@attribute directive is used
-          if @docstring =~ /^@!?(method|attribute)\b/
-            return register_docstring(nil)
-          end
-
-          object = MethodObject.new(namespace, method_name, scope)
-          object.signature = method_signature
-          register(object)
-        end
-
-        def register_docstring(object, docstring = @docstring, stmt = statement)
-          super
-        end
-
-        private
-
-        def implicit_docstring?
-          tags = %w(method attribute overload visibility scope return)
-          tags.any? {|tag| @docstring =~ /^@!?#{tag}\b/ }
-        end
-
-        def method_name
-          name = call_params.first || ""
-          if name =~ /^#{CodeObjects::METHODNAMEMATCH}$/
-            name
-          else
-            raise UndocumentableError, "method, missing name"
-          end
-        end
-
-        def method_signature
-          "def #{method_name}"
-        end
-
-        def find_attached_macro
-          Registry.all(:macro).each do |macro|
-            next unless macro.method_object
-            next unless macro_name_matches(macro)
-            (namespace.inheritance_tree(true) + [P('Object')]).each do |obj|
-              return macro if obj == macro.method_object.namespace
-            end
-          end
-          nil
-        end
-
-        # @return [Boolean] whether caller method matches a macro or
-        #   its alias names.
-        def macro_name_matches(macro)
-          objs = [macro.method_object]
-          if objs.first.type != :proxy && objs.first.respond_to?(:aliases)
-            objs.concat(objs.first.aliases)
-          end
-
-          objs.any? {|obj| obj.name.to_s == caller_method.to_s }
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  module Handlers
+    module Ruby
+      module DSLHandlerMethods
+        include CodeObjects
+        include Parser
+
+        IGNORE_METHODS = Hash[*%w(alias alias_method autoload attr attr_accessor
+          attr_reader attr_writer extend include module_function public private
+          protected private_constant private_class_method public_class_method).
+          map {|n| [n, true] }.flatten]
+
+        def handle_comments
+          return if IGNORE_METHODS[caller_method]
+
+          @docstring = statement.comments || ""
+          @docstring = @docstring.join("\n") if @docstring.is_a?(Array)
+
+          attaching = false
+          if @docstring =~ /^@!?macro\s+\[[^\]]*attach/
+            register_docstring(nil)
+            @docstring = ""
+            attaching = true
+          end
+
+          macro = find_attached_macro
+          if macro
+            txt = macro.expand([caller_method, *call_params], statement.source)
+            @docstring += "\n" + txt
+
+            # macro may have a directive
+            return register_docstring(nil) if !attaching && txt.match(/^\s*@!/)
+          elsif !statement.comments_hash_flag && !implicit_docstring?
+            return register_docstring(nil)
+          end
+
+          # ignore DSL definitions if @method/@attribute directive is used
+          if @docstring =~ /^@!?(method|attribute)\b/
+            return register_docstring(nil)
+          end
+
+          object = MethodObject.new(namespace, method_name, scope)
+          object.signature = method_signature
+          register(object)
+        end
+
+        def register_docstring(object, docstring = @docstring, stmt = statement)
+          super
+        end
+
+        private
+
+        def implicit_docstring?
+          tags = %w(method attribute overload visibility scope return)
+          tags.any? {|tag| @docstring =~ /^@!?#{tag}\b/ }
+        end
+
+        def method_name
+          name = call_params.first || ""
+          if name =~ /^#{CodeObjects::METHODNAMEMATCH}$/
+            name
+          else
+            raise UndocumentableError, "method, missing name"
+          end
+        end
+
+        def method_signature
+          "def #{method_name}"
+        end
+
+        def find_attached_macro
+          Registry.all(:macro).each do |macro|
+            next unless macro.method_object
+            next unless macro_name_matches(macro)
+            (namespace.inheritance_tree(true) + [P('Object')]).each do |obj|
+              return macro if obj == macro.method_object.namespace
+            end
+          end
+          nil
+        end
+
+        # @return [Boolean] whether caller method matches a macro or
+        #   its alias names.
+        def macro_name_matches(macro)
+          objs = [macro.method_object]
+          if objs.first.type != :proxy && objs.first.respond_to?(:aliases)
+            objs.concat(objs.first.aliases)
+          end
+
+          objs.any? {|obj| obj.name.to_s == caller_method.to_s }
+        end
+      end
+    end
+  end
+end