yard 0.9.17 → 0.9.22

data/lib/yard/handlers/c/init_handler.rb

@@ -1,20 +1,20 @@
-# frozen_string_literal: true
-# Handles the Init_Libname() method
-class YARD::Handlers::C::InitHandler < YARD::Handlers::C::Base
-  MATCH = /\A\s*(?:\S+\s+)*void\s+(?:[Ii]nit_)?(\w+)\s*/
-  handles MATCH
-  statement_class ToplevelStatement
-
-  process do
-    parse_block
-    decl = statement.declaration[MATCH, 1]
-    if decl
-      ns = namespace_for_variable(decl)
-      if ns.is_a?(YARD::CodeObjects::NamespaceObject) && ns.docstring.blank?
-        if statement.comments
-          register_docstring(ns, statement.comments.source, statement)
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+# Handles the Init_Libname() method
+class YARD::Handlers::C::InitHandler < YARD::Handlers::C::Base
+  MATCH = /\A\s*(?:\S+\s+)*void\s+(?:[Ii]nit_)?(\w+)\s*/
+  handles MATCH
+  statement_class ToplevelStatement
+
+  process do
+    parse_block
+    decl = statement.declaration[MATCH, 1]
+    if decl
+      ns = namespace_for_variable(decl)
+      if ns.is_a?(YARD::CodeObjects::NamespaceObject) && ns.docstring.blank?
+        if statement.comments
+          register_docstring(ns, statement.comments.source, statement)
+        end
+      end
+    end
+  end
+end

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

@@ -1,45 +1,45 @@
-# frozen_string_literal: true
-class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
-  MATCH1 = /rb_define_
-                 (
-                    singleton_method |
-                    method           |
-                    module_function  |
-                    private_method
-                 )
-                 \s*\(\s*([\w\.]+)\s*,
-                   \s*"([^"]+)"\s*,
-                   \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?\s*,
-                   \s*(-?\w+)\s*\)/xm
-  MATCH2 = /rb_define_global_function\s*\(
-                \s*"([^"]+)",
-                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
-                \s*(-?\w+)\s*\)/xm
-  MATCH3 = /define_filetest_function\s*\(
-                \s*"([^"]+)",
-                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
-                \s*(-?\w+)\s*\)/xm
-  handles MATCH1
-  handles MATCH2
-  handles MATCH3
-  statement_class BodyStatement
-
-  process do
-    statement.source.scan(MATCH1) do |type, var_name, name, func_name, _param_count|
-      break if var_name == "ruby_top_self"
-      break if var_name == "nstr"
-      break if var_name == "envtbl"
-
-      var_name = "rb_cObject" if var_name == "rb_mKernel"
-      handle_method(type, var_name, name, func_name)
-    end
-
-    statement.source.scan(MATCH2) do |name, func_name, _param_count|
-      handle_method("method", "rb_mKernel", name, func_name)
-    end
-
-    statement.source.scan(MATCH3) do |name, func_name, _param_count|
-      handle_method("singleton_method", "rb_cFile", name, func_name)
-    end
-  end
-end
+# frozen_string_literal: true
+class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
+  MATCH1 = /rb_define_
+                 (
+                    singleton_method |
+                    method           |
+                    module_function  |
+                    private_method
+                 )
+                 \s*\(\s*([\w\.]+)\s*,
+                   \s*"([^"]+)"\s*,
+                   \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?\s*,
+                   \s*(-?\w+)\s*\)/xm
+  MATCH2 = /rb_define_global_function\s*\(
+                \s*"([^"]+)",
+                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
+                \s*(-?\w+)\s*\)/xm
+  MATCH3 = /define_filetest_function\s*\(
+                \s*"([^"]+)",
+                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
+                \s*(-?\w+)\s*\)/xm
+  handles MATCH1
+  handles MATCH2
+  handles MATCH3
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH1) do |type, var_name, name, func_name, _param_count|
+      break if var_name == "ruby_top_self"
+      break if var_name == "nstr"
+      break if var_name == "envtbl"
+
+      var_name = "rb_cObject" if var_name == "rb_mKernel"
+      handle_method(type, var_name, name, func_name)
+    end
+
+    statement.source.scan(MATCH2) do |name, func_name, _param_count|
+      handle_method("method", "rb_mKernel", name, func_name)
+    end
+
+    statement.source.scan(MATCH3) do |name, func_name, _param_count|
+      handle_method("singleton_method", "rb_cFile", name, func_name)
+    end
+  end
+end

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

@@ -1,21 +1,21 @@
-# frozen_string_literal: true
-class YARD::Handlers::C::MixinHandler < YARD::Handlers::C::Base
-  MATCH = /rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/
-  handles MATCH
-  statement_class BodyStatement
-
-  process do
-    statement.source.scan(MATCH) do |klass_var, mixin_var|
-      namespace = namespace_for_variable(klass_var)
-      ensure_loaded!(namespace)
-
-      var = namespace_for_variable(mixin_var)
-      if var
-        namespace.mixins(:instance) << var
-      else
-        raise YARD::Parser::UndocumentableError,
-          "CRuby mixin for unrecognized variable '#{mixin_var}'"
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+class YARD::Handlers::C::MixinHandler < YARD::Handlers::C::Base
+  MATCH = /rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/
+  handles MATCH
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH) do |klass_var, mixin_var|
+      namespace = namespace_for_variable(klass_var)
+      ensure_loaded!(namespace)
+
+      var = namespace_for_variable(mixin_var)
+      if var
+        namespace.mixins(:instance) << var
+      else
+        raise YARD::Parser::UndocumentableError,
+          "CRuby mixin for unrecognized variable '#{mixin_var}'"
+      end
+    end
+  end
+end

data/lib/yard/handlers/c/module_handler.rb

@@ -1,17 +1,17 @@
-# frozen_string_literal: true
-class YARD::Handlers::C::ModuleHandler < YARD::Handlers::C::Base
-  MATCH1 = /([\w\.]+)\s* = \s*rb_define_module\s*\(\s*"([\w:]+)"\s*\)/mx
-  MATCH2 = /([\w\.]+)\s* = \s*rb_define_module_under\s*\(\s*(\w+),\s*"(\w+)"\s*\)/mx
-  handles MATCH1
-  handles MATCH2
-  statement_class BodyStatement
-
-  process do
-    statement.source.scan(MATCH1) do |var_name, module_name|
-      handle_module(var_name, module_name)
-    end
-    statement.source.scan(MATCH2) do |var_name, in_module, module_name|
-      handle_module(var_name, module_name, in_module)
-    end
-  end
-end
+# frozen_string_literal: true
+class YARD::Handlers::C::ModuleHandler < YARD::Handlers::C::Base
+  MATCH1 = /([\w\.]+)\s* = \s*rb_define_module\s*\(\s*"([\w:]+)"\s*\)/mx
+  MATCH2 = /([\w\.]+)\s* = \s*rb_define_module_under\s*\(\s*(\w+),\s*"(\w+)"\s*\)/mx
+  handles MATCH1
+  handles MATCH2
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH1) do |var_name, module_name|
+      handle_module(var_name, module_name)
+    end
+    statement.source.scan(MATCH2) do |var_name, in_module, module_name|
+      handle_module(var_name, module_name, in_module)
+    end
+  end
+end

data/lib/yard/handlers/c/override_comment_handler.rb

@@ -1,31 +1,31 @@
-# frozen_string_literal: true
-# Parses comments
-class YARD::Handlers::C::OverrideCommentHandler < YARD::Handlers::C::Base
-  handles(/./)
-  statement_class Comment
-
-  process do
-    return if statement.overrides.empty?
-    statement.overrides.each do |type, name|
-      override_comments << [name, statement]
-      obj = nil
-      case type
-      when :class
-        name, superclass = *name.split(/\s*<\s*/)
-        obj = YARD::CodeObjects::ClassObject.new(:root, name)
-        obj.superclass = "::#{superclass}" if superclass
-      when :module
-        obj = YARD::CodeObjects::ModuleObject.new(:root, name)
-      end
-      register(obj)
-    end
-  end
-
-  def register_docstring(object, docstring = statement.source, stmt = statement)
-    super
-  end
-
-  def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
-    super
-  end
-end
+# frozen_string_literal: true
+# Parses comments
+class YARD::Handlers::C::OverrideCommentHandler < YARD::Handlers::C::Base
+  handles(/./)
+  statement_class Comment
+
+  process do
+    return if statement.overrides.empty?
+    statement.overrides.each do |type, name|
+      override_comments << [name, statement]
+      obj = nil
+      case type
+      when :class
+        name, superclass = *name.split(/\s*<\s*/)
+        obj = YARD::CodeObjects::ClassObject.new(:root, name)
+        obj.superclass = "::#{superclass}" if superclass
+      when :module
+        obj = YARD::CodeObjects::ModuleObject.new(:root, name)
+      end
+      register(obj)
+    end
+  end
+
+  def register_docstring(object, docstring = statement.source, stmt = statement)
+    super
+  end
+
+  def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
+    super
+  end
+end

data/lib/yard/handlers/c/path_handler.rb

@@ -1,11 +1,11 @@
-# frozen_string_literal: true
-class YARD::Handlers::C::PathHandler < YARD::Handlers::C::Base
-  MATCH = /([\w\.]+)\s* = \s*rb_path2class\s*\(\s*"([\w:]+)"\)/mx
-  handles MATCH
-
-  process do
-    statement.source.scan(MATCH) do |var_name, path|
-      namespaces[var_name] = P(path)
-    end
-  end
-end
+# frozen_string_literal: true
+class YARD::Handlers::C::PathHandler < YARD::Handlers::C::Base
+  MATCH = /([\w\.]+)\s* = \s*rb_path2class\s*\(\s*"([\w:]+)"\)/mx
+  handles MATCH
+
+  process do
+    statement.source.scan(MATCH) do |var_name, path|
+      namespaces[var_name] = P(path)
+    end
+  end
+end

data/lib/yard/handlers/c/struct_handler.rb

@@ -1,13 +1,13 @@
-# frozen_string_literal: true
-class YARD::Handlers::C::StructHandler < YARD::Handlers::C::Base
-  MATCH = /([\w\.]+)\s*=\s*(?:rb_struct_define_without_accessor)\s*
-           \(\s*"([\w:]+)"\s*,\s*(\w+)\s*/mx
-  handles MATCH
-  statement_class BodyStatement
-
-  process do
-    statement.source.scan(MATCH) do |var_name, class_name, parent|
-      handle_class(var_name, class_name, parent)
-    end
-  end
-end
+# frozen_string_literal: true
+class YARD::Handlers::C::StructHandler < YARD::Handlers::C::Base
+  MATCH = /([\w\.]+)\s*=\s*(?:rb_struct_define_without_accessor)\s*
+           \(\s*"([\w:]+)"\s*,\s*(\w+)\s*/mx
+  handles MATCH
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH) do |var_name, class_name, parent|
+      handle_class(var_name, class_name, parent)
+    end
+  end
+end

data/lib/yard/handlers/c/symbol_handler.rb

@@ -1,8 +1,8 @@
-# frozen_string_literal: true
-# Keeps track of function bodies for symbol lookup during Ruby method declarations
-class YARD::Handlers::C::SymbolHandler < YARD::Handlers::C::Base
-  MATCH = /\A\s*(?:(?:\w+)\s+)?(?:intern\s+)?VALUE\s+(\w+)\s*\(/
-  handles MATCH
-  statement_class ToplevelStatement
-  process { symbols[statement.source[MATCH, 1]] = statement }
-end
+# frozen_string_literal: true
+# Keeps track of function bodies for symbol lookup during Ruby method declarations
+class YARD::Handlers::C::SymbolHandler < YARD::Handlers::C::Base
+  MATCH = /\A\s*(?:(?:\w+)\s+)?(?:intern\s+)?VALUE\s+(\w+)\s*\(/
+  handles MATCH
+  statement_class ToplevelStatement
+  process { symbols[statement.source[MATCH, 1]] = statement }
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module YARD::Handlers
+  module Common
+    # Shared functionality between Ruby and C method handlers.
+    module MethodHandler
+      # @param [MethodObject] obj
+      def add_predicate_return_tag(obj)
+        if obj.tag(:return) && (obj.tag(:return).types || []).empty?
+          obj.tag(:return).types = ['Boolean']
+        elsif obj.tag(:return).nil?
+          unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
+            obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/processor.rb

@@ -1,200 +1,200 @@
-# frozen_string_literal: true
-require 'ostruct'
-
-module YARD
-  module Handlers
-    # Iterates over all statements in a file and delegates them to the
-    # {Handlers::Base} objects that are registered to handle the statement.
-    #
-    # This class is passed to each handler and keeps overall processing state.
-    # For example, if the {#visibility} is set in a handler, all following
-    # statements will have access to this state. This allows "public",
-    # "protected" and "private" statements to be handled in classes and modules.
-    # In addition, the {#namespace} can be set during parsing to control
-    # where objects are being created from. You can also access extra stateful
-    # properties that any handler can set during the duration of the post
-    # processing of a file from {#extra_state}. If you need to access state
-    # across different files, look at {#globals}.
-    #
-    # @see Handlers::Base
-    class Processor
-      class << self
-        # Registers a new namespace for handlers of the given type.
-        # @since 0.6.0
-        def register_handler_namespace(type, ns)
-          namespace_for_handler[type] = ns
-        end
-
-        # @return [Hash] a list of registered parser type extensions
-        # @private
-        # @since 0.6.0
-        attr_reader :namespace_for_handler
-        undef namespace_for_handler
-        def namespace_for_handler; @@parser_type_extensions ||= {} end
-      end
-
-      register_handler_namespace :ruby, Ruby
-      register_handler_namespace :ruby18, Ruby::Legacy
-      register_handler_namespace :c, C
-
-      # @return [String] the filename
-      attr_accessor :file
-
-      # @return [CodeObjects::NamespaceObject] the current namespace
-      attr_accessor :namespace
-
-      # @return [Symbol] the current visibility (public, private, protected)
-      attr_accessor :visibility
-
-      # @return [Symbol] the current scope (class, instance)
-      attr_accessor :scope
-
-      # @return [CodeObjects::Base, nil] unlike the namespace, the owner
-      #   is a non-namespace object that should be stored between statements.
-      #   For instance, when parsing a method body, the {CodeObjects::MethodObject}
-      #   is set as the owner, in case any extra method information is processed.
-      attr_accessor :owner
-
-      # @return [Symbol] the parser type (:ruby, :ruby18, :c)
-      attr_accessor :parser_type
-
-      # Handlers can share state for the entire post processing stage through
-      # this attribute. Note that post processing stage spans multiple files.
-      # To share state only within a single file, use {#extra_state}
-      #
-      # @example Sharing state among two handlers
-      #   class Handler1 < YARD::Handlers::Ruby::Base
-      #     handles :class
-      #     process { globals.foo = :bar }
-      #   end
-      #
-      #   class Handler2 < YARD::Handlers::Ruby::Base
-      #     handles :method
-      #     process { puts globals.foo }
-      #   end
-      # @return [OpenStruct] global shared state for post-processing stage
-      # @see #extra_state
-      attr_accessor :globals
-
-      # Share state across different handlers inside of a file.
-      # This attribute is similar to {#visibility}, {#scope}, {#namespace}
-      # and {#owner}, in that they all maintain state across all handlers
-      # for the entire source file. Use this attribute to store any data
-      # your handler might need to save during the parsing of a file. If
-      # you need to save state across files, see {#globals}.
-      #
-      # @return [OpenStruct] an open structure that can store arbitrary data
-      # @see #globals
-      attr_accessor :extra_state
-
-      # Creates a new Processor for a +file+.
-      # @param [Parser::SourceParser] parser the parser used to initialize the processor
-      def initialize(parser)
-        @file = parser.file || "(stdin)"
-        @namespace = YARD::Registry.root
-        @visibility = :public
-        @scope = :instance
-        @owner = @namespace
-        @parser_type = parser.parser_type
-        @handlers_loaded = {}
-        @globals = parser.globals || OpenStruct.new
-        @extra_state = OpenStruct.new
-        load_handlers
-      end
-
-      # Processes a list of statements by finding handlers to process each
-      # one.
-      #
-      # @param [Array] statements a list of statements
-      # @return [void]
-      def process(statements)
-        statements.each_with_index do |stmt, _index|
-          find_handlers(stmt).each do |handler|
-            begin
-              handler.new(self, stmt).process
-            rescue HandlerAborted
-              log.debug "#{handler} cancelled from #{caller.last}"
-              log.debug "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
-            rescue NamespaceMissingError => missingerr
-              log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized.\n" \
-                       "If this class/method is part of your source tree, this will affect your documentation results.\n" \
-                       "You can correct this issue by loading the source file for this object before `#{file}'\n"
-            rescue Parser::UndocumentableError => undocerr
-              log.warn "in #{handler}: Undocumentable #{undocerr.message}\n" \
-                       "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
-            rescue => e
-              log.error "Unhandled exception in #{handler}:\n" \
-                        "  in `#{file}`:#{stmt.line}:\n\n#{stmt.show}\n"
-              log.backtrace(e)
-            end
-          end
-        end
-      end
-
-      # Continue parsing the remainder of the files in the +globals.ordered_parser+
-      # object. After the remainder of files are parsed, processing will continue
-      # on the current file.
-      #
-      # @return [void]
-      # @see Parser::OrderedParser
-      def parse_remaining_files
-        if globals.ordered_parser
-          globals.ordered_parser.parse
-          log.debug("Re-processing #{@file}...")
-        end
-      end
-
-      # Searches for all handlers in {Base.subclasses} that match the +statement+
-      #
-      # @param statement the statement object to match.
-      # @return [Array<Base>] a list of handlers to process the statement with.
-      def find_handlers(statement)
-        Base.subclasses.find_all do |handler|
-          handler_base_class > handler &&
-            (handler.namespace_only? ? owner.is_a?(CodeObjects::NamespaceObject) : true) &&
-            handles?(handler, statement)
-        end
-      end
-
-      private
-
-      def handles?(handler, statement)
-        return false unless handler.matches_file?(file)
-        if handler.method(:handles?).arity == 1
-          handler.handles?(statement)
-        elsif [-1, 2].include?(handler.method(:handles?).arity)
-          handler.handles?(statement, self)
-        end
-      end
-
-      # Returns the handler base class
-      # @return [Base] the base class
-      def handler_base_class
-        handler_base_namespace.const_get(:Base)
-      end
-
-      # The module holding the handlers to be loaded
-      #
-      # @return [Module] the module containing the handlers depending on
-      #   {#parser_type}.
-      def handler_base_namespace
-        self.class.namespace_for_handler[parser_type]
-      end
-
-      # Loads handlers from {#handler_base_namespace}. This ensures that
-      # Ruby1.9 handlers are never loaded into 1.8; also lowers the amount
-      # of modules that are loaded
-      # @return [void]
-      def load_handlers
-        return if @handlers_loaded[parser_type]
-        handler_base_namespace.constants.each do |c|
-          const = handler_base_namespace.const_get(c)
-          unless Handlers::Base.subclasses.include?(const)
-            Handlers::Base.subclasses << const
-          end
-        end
-        @handlers_loaded[parser_type] = true
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+require 'ostruct'
+
+module YARD
+  module Handlers
+    # Iterates over all statements in a file and delegates them to the
+    # {Handlers::Base} objects that are registered to handle the statement.
+    #
+    # This class is passed to each handler and keeps overall processing state.
+    # For example, if the {#visibility} is set in a handler, all following
+    # statements will have access to this state. This allows "public",
+    # "protected" and "private" statements to be handled in classes and modules.
+    # In addition, the {#namespace} can be set during parsing to control
+    # where objects are being created from. You can also access extra stateful
+    # properties that any handler can set during the duration of the post
+    # processing of a file from {#extra_state}. If you need to access state
+    # across different files, look at {#globals}.
+    #
+    # @see Handlers::Base
+    class Processor
+      class << self
+        # Registers a new namespace for handlers of the given type.
+        # @since 0.6.0
+        def register_handler_namespace(type, ns)
+          namespace_for_handler[type] = ns
+        end
+
+        # @return [Hash] a list of registered parser type extensions
+        # @private
+        # @since 0.6.0
+        attr_reader :namespace_for_handler
+        undef namespace_for_handler
+        def namespace_for_handler; @@parser_type_extensions ||= {} end
+      end
+
+      register_handler_namespace :ruby, Ruby
+      register_handler_namespace :ruby18, Ruby::Legacy
+      register_handler_namespace :c, C
+
+      # @return [String] the filename
+      attr_accessor :file
+
+      # @return [CodeObjects::NamespaceObject] the current namespace
+      attr_accessor :namespace
+
+      # @return [Symbol] the current visibility (public, private, protected)
+      attr_accessor :visibility
+
+      # @return [Symbol] the current scope (class, instance)
+      attr_accessor :scope
+
+      # @return [CodeObjects::Base, nil] unlike the namespace, the owner
+      #   is a non-namespace object that should be stored between statements.
+      #   For instance, when parsing a method body, the {CodeObjects::MethodObject}
+      #   is set as the owner, in case any extra method information is processed.
+      attr_accessor :owner
+
+      # @return [Symbol] the parser type (:ruby, :ruby18, :c)
+      attr_accessor :parser_type
+
+      # Handlers can share state for the entire post processing stage through
+      # this attribute. Note that post processing stage spans multiple files.
+      # To share state only within a single file, use {#extra_state}
+      #
+      # @example Sharing state among two handlers
+      #   class Handler1 < YARD::Handlers::Ruby::Base
+      #     handles :class
+      #     process { globals.foo = :bar }
+      #   end
+      #
+      #   class Handler2 < YARD::Handlers::Ruby::Base
+      #     handles :method
+      #     process { puts globals.foo }
+      #   end
+      # @return [OpenStruct] global shared state for post-processing stage
+      # @see #extra_state
+      attr_accessor :globals
+
+      # Share state across different handlers inside of a file.
+      # This attribute is similar to {#visibility}, {#scope}, {#namespace}
+      # and {#owner}, in that they all maintain state across all handlers
+      # for the entire source file. Use this attribute to store any data
+      # your handler might need to save during the parsing of a file. If
+      # you need to save state across files, see {#globals}.
+      #
+      # @return [OpenStruct] an open structure that can store arbitrary data
+      # @see #globals
+      attr_accessor :extra_state
+
+      # Creates a new Processor for a +file+.
+      # @param [Parser::SourceParser] parser the parser used to initialize the processor
+      def initialize(parser)
+        @file = parser.file || "(stdin)"
+        @namespace = YARD::Registry.root
+        @visibility = :public
+        @scope = :instance
+        @owner = @namespace
+        @parser_type = parser.parser_type
+        @handlers_loaded = {}
+        @globals = parser.globals || OpenStruct.new
+        @extra_state = OpenStruct.new
+        load_handlers
+      end
+
+      # Processes a list of statements by finding handlers to process each
+      # one.
+      #
+      # @param [Array] statements a list of statements
+      # @return [void]
+      def process(statements)
+        statements.each_with_index do |stmt, _index|
+          find_handlers(stmt).each do |handler|
+            begin
+              handler.new(self, stmt).process
+            rescue HandlerAborted
+              log.debug "#{handler} cancelled from #{caller.last}"
+              log.debug "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
+            rescue NamespaceMissingError => missingerr
+              log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized.\n" \
+                       "If this class/method is part of your source tree, this will affect your documentation results.\n" \
+                       "You can correct this issue by loading the source file for this object before `#{file}'\n"
+            rescue Parser::UndocumentableError => undocerr
+              log.warn "in #{handler}: Undocumentable #{undocerr.message}\n" \
+                       "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
+            rescue => e
+              log.error "Unhandled exception in #{handler}:\n" \
+                        "  in `#{file}`:#{stmt.line}:\n\n#{stmt.show}\n"
+              log.backtrace(e)
+            end
+          end
+        end
+      end
+
+      # Continue parsing the remainder of the files in the +globals.ordered_parser+
+      # object. After the remainder of files are parsed, processing will continue
+      # on the current file.
+      #
+      # @return [void]
+      # @see Parser::OrderedParser
+      def parse_remaining_files
+        if globals.ordered_parser
+          globals.ordered_parser.parse
+          log.debug("Re-processing #{@file}...")
+        end
+      end
+
+      # Searches for all handlers in {Base.subclasses} that match the +statement+
+      #
+      # @param statement the statement object to match.
+      # @return [Array<Base>] a list of handlers to process the statement with.
+      def find_handlers(statement)
+        Base.subclasses.find_all do |handler|
+          handler_base_class > handler &&
+            (handler.namespace_only? ? owner.is_a?(CodeObjects::NamespaceObject) : true) &&
+            handles?(handler, statement)
+        end
+      end
+
+      private
+
+      def handles?(handler, statement)
+        return false unless handler.matches_file?(file)
+        if handler.method(:handles?).arity == 1
+          handler.handles?(statement)
+        elsif [-1, 2].include?(handler.method(:handles?).arity)
+          handler.handles?(statement, self)
+        end
+      end
+
+      # Returns the handler base class
+      # @return [Base] the base class
+      def handler_base_class
+        handler_base_namespace.const_get(:Base)
+      end
+
+      # The module holding the handlers to be loaded
+      #
+      # @return [Module] the module containing the handlers depending on
+      #   {#parser_type}.
+      def handler_base_namespace
+        self.class.namespace_for_handler[parser_type]
+      end
+
+      # Loads handlers from {#handler_base_namespace}. This ensures that
+      # Ruby1.9 handlers are never loaded into 1.8; also lowers the amount
+      # of modules that are loaded
+      # @return [void]
+      def load_handlers
+        return if @handlers_loaded[parser_type]
+        handler_base_namespace.constants.each do |c|
+          const = handler_base_namespace.const_get(c)
+          unless Handlers::Base.subclasses.include?(const)
+            Handlers::Base.subclasses << const
+          end
+        end
+        @handlers_loaded[parser_type] = true
+      end
+    end
+  end
+end