yard 0.7.5 → 0.8.0

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

@@ -0,0 +1,26 @@
+class YARD::Handlers::C::ClassHandler < YARD::Handlers::C::Base
+  MATCH1 = /([\w\.]+)\s* = \s*(?:rb_define_class|boot_defclass)\s*
+            \(
+               \s*"([\w:]+)",
+               \s*(\w+|0)\s*
+            \)/mx
+
+  MATCH2 = /([\w\.]+)\s* = \s*rb_define_class_under\s*
+            \(
+               \s*(\w+),
+               \s*"(\w+)"(?:,
+               \s*([\w\*\s\(\)\.\->]+)\s*)?  # for SWIG
+            \s*\)/mx
+  handles MATCH1
+  handles MATCH2
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH1) do |var_name, class_name, parent|
+      handle_class(var_name, class_name, parent)
+    end
+    statement.source.scan(MATCH2) do |var_name, in_module, class_name, parent|
+      handle_class(var_name, class_name, parent, in_module)
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+class YARD::Handlers::C::ConstantHandler < YARD::Handlers::C::Base
+  MATCH = %r{\brb_define_((?:readonly_)?variable|(?:global_)?const)
+                \s*\((?:\s*(\w+),)?\s*"(\w+)",\s*(.*?)\s*\)\s*;}xm
+  handles MATCH
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH) do |type, var_name, const_name, value|
+      handle_constants(type, var_name, const_name, value)
+    end
+  end
+end

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

@@ -0,0 +1,165 @@
+module YARD
+  module Handlers
+    module C
+      module HandlerMethods
+        include Parser::C
+        include CodeObjects
+
+        def handle_class(var_name, class_name, parent, in_module = nil)
+          parent = nil if parent == "0"
+          namespace = in_module ? namespace_for_variable(in_module) : Registry.root
+          register ClassObject.new(namespace, class_name) do |obj|
+            if parent
+              parent_class = namespace_for_variable(parent)
+              if parent_class.is_a?(Proxy)
+                obj.superclass = "::#{parent_class.path}"
+                obj.superclass.type = :class
+              else
+                obj.superclass = parent_class
+              end
+            end
+            namespaces[var_name] = obj
+            register_file_info(obj, statement.file, statement.line)
+          end
+        end
+
+        def handle_module(var_name, module_name, in_module = nil)
+          namespace = in_module ? namespace_for_variable(in_module) : Registry.root
+          register ModuleObject.new(namespace, module_name) do |obj|
+            namespaces[var_name] = obj
+            register_file_info(obj, statement.file, statement.line)
+          end
+        end
+
+        def handle_method(scope, var_name, name, func_name, source_file = nil)
+          visibility = :public
+          case scope
+          when "singleton_method"; scope = :class
+          when "module_function"; scope = :module
+          when "private_method"; scope = :instance; visibility = :private
+          else; scope = :instance
+          end
+
+          namespace = namespace_for_variable(var_name)
+          return if namespace.nil? # XXX: raise UndocumentableError might be too noisy.
+          register MethodObject.new(namespace, name, scope) do |obj|
+            register_visibility(obj, visibility)
+            find_method_body(obj, func_name)
+            obj.docstring.add_tag(Tags::Tag.new(:return, '', 'Boolean')) if name =~ /\?$/
+          end
+        end
+
+        def handle_attribute(var_name, name, read, write)
+          values = {:read => read.to_i, :write => write.to_i}
+          {:read => name, :write => "#{name}="}.each do |type, meth_name|
+            next unless values[type] > 0
+            obj = handle_method(:instance, var_name, meth_name, nil)
+            obj.namespace.attributes[:instance][name] ||= SymbolHash[:read => nil, :write => nil]
+            obj.namespace.attributes[:instance][name][type] = obj
+          end
+        end
+
+        def handle_alias(var_name, new_name, old_name)
+          namespace = namespace_for_variable(var_name)
+          new_meth, old_meth = new_name.to_sym, old_name.to_sym
+          old_obj = namespace.child(:name => old_meth, :scope => :instance)
+          new_obj = register MethodObject.new(namespace, new_meth, :instance) do |o|
+            register_visibility(o, visibility)
+            register_file_info(o, statement.file, statement.line)
+          end
+
+          if old_obj
+            new_obj.signature = old_obj.signature
+            new_obj.source = old_obj.source
+            new_obj.docstring = old_obj.docstring
+            new_obj.docstring.object = new_obj
+          else
+            new_obj.signature = "def #{new_meth}" # this is all we know.
+          end
+
+          namespace.aliases[new_obj] = old_meth
+        end
+
+        def handle_constants(type, var_name, const_name, value)
+          return unless type == 'const'
+          namespace = namespace_for_variable(var_name)
+          register ConstantObject.new(namespace, const_name) do |obj|
+            obj.source_type = :c
+            obj.value = value
+            register_file_info(obj, statement.file, statement.line)
+            find_constant_docstring(obj)
+          end
+        end
+
+        private
+
+        def find_constant_docstring(object)
+          comment = nil
+
+          # look inside overrides for declaration value
+          override_comments.each do |name, override_comment|
+            next unless override_comment.file == statement.file
+            just_const_name = name.gsub(/\A.+::/, '')
+            if object.path == name || object.name.to_s == just_const_name
+              comment = override_comment.source
+              stmt = override_comment
+              break
+            end
+          end
+
+          # use any comments on this statement as a last resort
+          if comment.nil? && statement.comments && statement.comments.source =~ /\S/
+            comment = statement.comments.source
+            stmt = statement.comments
+          end
+
+          # In the case of rb_define_const, the definition and comment are in
+          # "/* definition: comment */" form.  The literal ':' and '\' characters
+          # can be escaped with a backslash.
+          if comment
+            comment.scan(/\A\s*(.*?[^\s\\]):\s*(.+)/m) do |new_value, new_comment|
+              object.value = new_value.gsub(/\\:/, ':')
+              comment = new_comment
+            end
+            register_docstring(object, comment, stmt)
+          end
+        end
+
+        def find_method_body(object, symbol)
+          file, in_file = statement.file, false
+          if statement.comments && statement.comments.source =~ /\A\s*in (\S+)\Z/
+            file, in_file = $1, true
+            process_file(file, object)
+          end
+
+          if src_stmt = symbols[symbol]
+            register_file_info(object, src_stmt.file, src_stmt.line, true)
+            register_source(object, src_stmt)
+            unless src_stmt.comments.nil? || src_stmt.comments.source.empty?
+              register_docstring(object, src_stmt.comments.source, src_stmt)
+              return # found docstring
+            end
+          end
+
+          # found source (possibly) but no docstring
+          # so look in overrides
+          override_comments.each do |name, override_comment|
+            next unless override_comment.file == file
+            name = name.gsub(/::([^:]+?)\Z/, '.\1')
+            just_method_name = name.gsub(/\A.+(#|::|\.)/, '')
+            just_method_name = 'initialize' if just_method_name == 'new'
+            if object.path == name || object.name.to_s == just_method_name
+              register_docstring(object, override_comment.source, override_comment)
+              return
+            end
+          end
+
+          # use any comments on this statement as a last resort
+          if !in_file && statement.comments && statement.comments.source =~ /\S/
+            register_docstring(object, statement.comments.source, statement)
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,35 @@
+class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
+  MATCH1 = %r{rb_define_
+                 (
+                    singleton_method |
+                    method           |
+                    module_function  |
+                    private_method
+                 )
+                 \s*\(\s*([\w\.]+),
+                   \s*"([^"]+)",
+                   \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
+                   \s*(-?\w+)\s*\)}xm
+  MATCH2 = %r{rb_define_global_function\s*\(
+                \s*"([^"]+)",
+                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
+                \s*(-?\w+)\s*\)}xm
+  handles MATCH1
+  handles MATCH2
+  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
+  end
+end

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

@@ -0,0 +1,13 @@
+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)
+      namespace.mixins(:instance) << namespace_for_variable(mixin_var)
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,22 @@
+# Parses comments
+class YARD::Handlers::C::OverrideCommentHandler < YARD::Handlers::C::Base
+  handles %r{.}
+  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_docstring(obj, statement.source, statement) if obj
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,12 @@
+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

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

data/lib/yard/handlers/processor.rb

@@ -35,6 +35,7 @@ module YARD
 
       register_handler_namespace :ruby, Ruby
       register_handler_namespace :ruby18, Ruby::Legacy
+      register_handler_namespace :c, C
 
       # @return [String] the filename
       attr_accessor :file
@@ -54,22 +55,19 @@ module YARD
       #   is set as the owner, in case any extra method information is processed.
       attr_accessor :owner
 
-      # @return [Boolean] whether or not {Parser::LoadOrderError} is raised
-      attr_accessor :load_order_errors
-
       # @return [Symbol] the parser type (:ruby, :ruby18, :c)
       attr_accessor :parser_type
-      
-      # Handlers can share state for the entire post processing stage through 
+
+      # 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 }
@@ -77,41 +75,29 @@ module YARD
       # @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 [String] file the name of the file that is being processed.
-      #   uses '(stdin)' if file is nil.
-      # @param [Boolean] load_order_error whether or not to raise {Parser::LoadOrderError}
-      #   when a file has unresolved references that need to be parsed first.
-      #   If these errors are raised, the processor will attempt to load all
-      #   other files before continuing to parse the file.
-      # @param [Symbol] parser_type the parser type (:ruby, :ruby18, :c) from
-      #   the parser. Used to select the handler (since handlers are specific
-      #   to a parser type).
-      # @param [OpenStruct] globals the object holding all state during the
-      #   post processing stage
-      def initialize(file = nil, load_order_errors = false, parser_type = Parser::SourceParser.parser_type, globals = nil)
-        @file = file || "(stdin)"
+      # @param [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
-        @load_order_errors = load_order_errors
-        @parser_type = parser_type
+        @parser_type = parser.parser_type
         @handlers_loaded = {}
-        @globals = globals || OpenStruct.new
+        @globals = parser.globals || OpenStruct.new
         @extra_state = OpenStruct.new
         load_handlers
       end
@@ -126,8 +112,6 @@ module YARD
           find_handlers(stmt).each do |handler|
             begin
               handler.new(self, stmt).process
-            rescue Parser::LoadOrderError => loaderr
-              raise # Pass this up
             rescue NamespaceMissingError => missingerr
               log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized."
               log.warn "If this class/method is part of your source tree, this will affect your documentation results."
@@ -145,6 +129,19 @@ module YARD
         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.
@@ -153,12 +150,21 @@ module YARD
         Base.subclasses.find_all do |handler|
           handler_base_class > handler &&
           (handler.namespace_only? ? owner.is_a?(CodeObjects::NamespaceObject) : true) &&
-          handler.matches_file?(file) && handler.handles?(statement)
+          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
@@ -179,7 +185,12 @@ module YARD
       # @return [void]
       def load_handlers
         return if @handlers_loaded[parser_type]
-        handler_base_namespace.constants.each {|c| handler_base_namespace.const_get(c) }
+        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