yard 0.7.5 → 0.8.0

data/lib/yard/handlers/base.rb

@@ -233,6 +233,7 @@ module YARD
         #   match for a handler. If no file match is specified, returns true.
         # @since 0.6.2
         def matches_file?(filename)
+          @in_files ||= nil # avoid ruby warnings
           return true unless @in_files
           @in_files.any? do |in_file|
             case in_file
@@ -251,8 +252,8 @@ module YARD
         # module so that the handler class can be extended with mixins that
         # override the +process+ method without alias chaining.
         #
-        # @macro yard.handlers.process
-        #   @method process
+        # @!macro yard.handlers.process
+        #   @!method process
         #   Main processing callback
         #   @return [void]
         # @see #process
@@ -297,8 +298,6 @@ module YARD
         raise NotImplementedError, "#{self} did not implement a #parse_block method for handling"
       end
 
-      protected
-
       # @return [Processor] the processor object that manages all global state
       #   during handling.
       attr_reader :parser
@@ -325,9 +324,10 @@ module YARD
 
       # (see Processor#extra_state)
       attr_reader :extra_state
-      
+
       undef owner, owner=, namespace, namespace=
       undef visibility, visibility=, scope, scope=
+      undef globals, extra_state
 
       def owner; parser.owner end
       def owner=(v) parser.owner=(v) end
@@ -388,62 +388,136 @@ module YARD
       def register(*objects)
         objects.flatten.each do |object|
           next unless object.is_a?(CodeObjects::Base)
-
-          begin
-            ensure_loaded!(object.namespace)
-            object.namespace.children << object
-          rescue NamespaceMissingError
-          end
-
-          # Yield the object to the calling block because ruby will parse the syntax
-          #
-          #     register obj = ClassObject.new {|o| ... }
-          #
-          # as the block for #register. We need to make sure this gets to the object.
+          register_ensure_loaded(object)
           yield(object) if block_given?
+          register_file_info(object)
+          register_source(object)
+          register_visibility(object)
+          register_docstring(object)
+          register_group(object)
+          register_dynamic(object)
+          register_module_function(object)
+        end
+        objects.size == 1 ? objects.first : objects
+      end
 
-          object.add_file(parser.file, statement.line, statement.comments)
+      # Ensures that the object's namespace is loaded before attaching it
+      # to the namespace.
+      #
+      # @param [CodeObjects::Base] object the object to register
+      # @return [void]
+      # @since 0.8.0
+      def register_ensure_loaded(object)
+        begin
+          ensure_loaded!(object.namespace)
+          object.namespace.children << object
+        rescue NamespaceMissingError
+        end
+      end
 
-          # Add docstring if there is one.
-          if statement.comments
-            object.docstring = Docstring.new(statement.comments, object)
-          end
+      # Registers the file/line of the declaration with the object
+      #
+      # @param [CodeObjects::Base] object the object to register
+      # @return [void]
+      # @since 0.8.0
+      def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
+        object.add_file(file, line, comments)
+      end
 
-          # Expand/create any @macro tags
-          expand_macro(object, find_or_create_macro(object))
+      # Registers any docstring found for the object and expands macros
+      #
+      # @param [CodeObjects::Base] object the object to register
+      # @return [void]
+      # @since 0.8.0
+      def register_docstring(object, docstring = statement.comments, stmt = statement)
+        docstring = docstring.join("\n") if Array === docstring
+        parser = DocstringParser.new
+        parser.parse(docstring || "", object, self)
 
-          # Add hash_flag/line_range
-          if statement.comments
-            object.docstring.hash_flag = statement.comments_hash_flag
-            object.docstring.line_range = statement.comments_range
-          end
+        if object && docstring
+          object.docstring = parser.to_docstring
 
-          # Add group information
-          if statement.group
-            unless object.namespace.is_a?(Proxy)
-              object.namespace.groups |= [statement.group]
-            end
-            object.group = statement.group
+          # Add hash_flag/line_range
+          if stmt
+            object.docstring.hash_flag = stmt.comments_hash_flag
+            object.docstring.line_range = stmt.comments_range
           end
+        end
 
-          # Add transitive tags
-          Tags::Library.transitive_tags.each do |tag|
-            next if object.namespace.is_a?(Proxy)
-            next unless object.namespace.has_tag?(tag)
-            next if object.has_tag?(tag)
-            object.docstring.add_tag(*object.namespace.tags(tag))
-          end
+        register_transitive_tags(object)
+      end
 
-          # Add source only to non-class non-module objects
-          unless object.is_a?(NamespaceObject)
-            object.source ||= statement
+      # Registers the object as being inside a specific group
+      #
+      # @param [CodeObjects::Base] object the object to register
+      # @return [void]
+      # @since 0.8.0
+      def register_group(object, group = extra_state.group)
+        if group
+          unless object.namespace.is_a?(Proxy)
+            object.namespace.groups |= [group]
           end
+          object.group = group
+        end
+      end
 
-          # Make it dynamic if its owner is not its namespace.
-          # This generally means it was defined in a method (or block of some sort)
-          object.dynamic = true if owner != namespace
+      # Registers any transitive tags from the namespace on the object
+      #
+      # @param [CodeObjects::Base, nil] object the object to register
+      # @return [void]
+      # @since 0.8.0
+      def register_transitive_tags(object)
+        return unless object
+        Tags::Library.transitive_tags.each do |tag|
+          next if object.namespace.is_a?(Proxy)
+          next unless object.namespace.has_tag?(tag)
+          next if object.has_tag?(tag)
+          object.docstring.add_tag(*object.namespace.tags(tag))
         end
-        objects.size == 1 ? objects.first : objects
+      end
+
+      # @param [CodeObjects::Base] object the object to register
+      # @return [void]
+      # @since 0.8.0
+      def register_source(object, source = statement, type = parser.parser_type)
+        return unless object.is_a?(MethodObject)
+        object.source ||= source
+        object.source_type = type
+      end
+
+      # Registers visibility on a method object. If the object does not
+      # respond to setting visibility, nothing is done.
+      #
+      # @param [#visibility=] object the object to register
+      # @param [Symbol] visibility the visibility to set on the object
+      # @since 0.8.0
+      def register_visibility(object, visibility = self.visibility)
+        return unless object.respond_to?(:visibility=)
+        object.visibility = visibility
+      end
+
+      # Registers the same method information on the module function, if
+      # the object was defined as a module function.
+      #
+      # @param [CodeObjects::Base] object the possible module function object
+      #   to copy data for
+      # @since 0.8.0
+      def register_module_function(object)
+        return unless object.is_a?(MethodObject)
+        return unless object.module_function?
+        modobj = MethodObject.new(object.namespace, object.name)
+        object.copy_to(modobj)
+        modobj.visibility = :private
+      end
+
+      # Registers the object as dynamic if the object is defined inside
+      # a method or block (owner != namespace)
+      #
+      # @param [CodeObjects::Base] object the object to register
+      # @return [void]
+      # @since 0.8.0
+      def register_dynamic(object)
+        object.dynamic = true if owner != namespace
       end
 
       # Ensures that a specific +object+ has been parsed and loaded into the
@@ -469,36 +543,22 @@ module YARD
       def ensure_loaded!(object, max_retries = 1)
         return if object.root?
         return object unless object.is_a?(Proxy)
-        unless parser.load_order_errors
-          if object.is_a?(Proxy)
-            raise NamespaceMissingError, object
-          else
-            nil
-          end
-        end
-
-        unless CONTINUATIONS_SUPPORTED
-          log.warn_no_continuations
-          raise NamespaceMissingError, object
-        end
 
         retries = 0
-        context = callcc {|c| c }
-        retries += 1
-
-        if object.is_a?(Proxy)
+        while object.is_a?(Proxy)
           if retries <= max_retries
             log.debug "Missing object #{object} in file `#{parser.file}', moving it to the back of the line."
-            raise Parser::LoadOrderError.new(context)
+            parser.parse_remaining_files
           else
             raise NamespaceMissingError, object
           end
+          retries += 1
         end
         object
       end
-      
+
       # @group Macro Support
-      
+
       # @abstract Implement this method to return the parameters in a method call
       #   statement. It should return an empty list if the statement is not a
       #   method call.
@@ -506,7 +566,7 @@ module YARD
       def call_params
         raise NotImplementedError
       end
-      
+
       # @abstract Implement this method to return the method being called in
       #   a method call. It should return nil if the statement is not a method
       #   call.
@@ -515,55 +575,6 @@ module YARD
       def caller_method
         raise NotImplementedError
       end
-      
-      # Attempts to find or create a macro if a +@macro+ tag is found in the
-      # docstring (or the object's docstring).
-      # 
-      # @param [Docstring, CodeObjects::Base] object_or_docstring the docstring
-      #   or it's object with which to check for a macro
-      # @return [CodeObjects::MacroObject] the newly created macro
-      # @return [nil] if the docstring does not create or reference a macro
-      def find_or_create_macro(object_or_docstring)
-        if object_or_docstring.is_a?(Docstring)
-          object, docstring = nil, object_or_docstring
-        else
-          object, docstring = object_or_docstring, object_or_docstring.docstring
-        end
-        return unless macro_tag = docstring.tag(:macro)
-        unless macro_tag.name
-          if object
-            log.warn "Invalid/missing macro name for #{object.path} (#{parser.file}:#{statement.line})"
-            return nil
-          else
-            raise UndocumentableError, 'method/attribute, missing macro name'
-          end
-        end
-        caller_obj = caller_method ? P(namespace, caller_method) : nil
-        if macro = MacroObject.find_or_create(docstring, caller_obj)
-          attached_method_name = caller_method
-          if object && object.is_a?(MethodObject) && object.scope == :class
-            macro.method_object = object
-            attached_method_name = object.name.to_s
-          end
-          if macro.attached?
-            globals.__attached_macros ||= {}
-            globals.__attached_macros[attached_method_name] ||= []
-            globals.__attached_macros[attached_method_name] |= [macro]
-          end
-        end
-        macro
-      end
-      
-      # Sets the docstring on +object+ to the expanded macro.
-      # @param [CodeObjects::Base] object the object to expand the macro on
-      # @param [CodeObjects::MacroObject] macro the macro object to expand
-      # @return [void]
-      def expand_macro(object, macro)
-        return unless macro
-        all_params = ([caller_method] + call_params).compact
-        data = MacroObject.apply_macro(macro, object.docstring, all_params, statement.source)
-        object.docstring = Docstring.new(data, object)
-      end
     end
   end
 end

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

@@ -0,0 +1,15 @@
+class YARD::Handlers::C::AliasHandler < YARD::Handlers::C::Base
+  MATCH = %r{rb_define_alias
+             \s*\(\s*([\w\.]+),
+             \s*"([^"]+)",
+             \s*"([^"]+)"\s*\)}xm
+  handles MATCH
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH) do |var_name, new_name, old_name|
+      var_name = "rb_cObject" if var_name == "rb_mKernel"
+      handle_alias(var_name, new_name, old_name)
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+class YARD::Handlers::C::AttributeHandler < YARD::Handlers::C::Base
+  MATCH = %r{rb_define_attr\s*\(\s*([\w\.]+),\s*"([^"]+)",\s*(0|1)\s*,\s*(0|1)\s*\)}
+  handles MATCH
+
+  process do
+    return if ToplevelStatement == statement
+    return if Comment === statement && statement.type != :multi
+    statement.source.scan(MATCH) do |var_name, name, read, write|
+      handle_attribute(var_name, name, read, write)
+    end
+  end
+
+end

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

@@ -0,0 +1,110 @@
+module YARD
+  module Handlers
+    module C
+      class Base < Handlers::Base
+        include YARD::Parser::C
+        include HandlerMethods
+
+        # @return [Boolean] whether the handler handles this statement
+        def self.handles?(statement, processor)
+          processor.globals.cruby_processed_files ||= {}
+          processor.globals.cruby_processed_files[processor.file] = true
+
+          if statement.respond_to? :declaration
+            src = statement.declaration
+          else
+            src = statement.source
+          end
+
+          handlers.any? do |a_handler|
+            statement_class >= statement.class &&
+              case a_handler
+              when String
+                src == a_handler
+              when Regexp
+                src =~ a_handler
+              end
+          end
+        end
+
+        def self.statement_class(type = nil)
+          type ? @statement_class = type : (@statement_class || Statement)
+        end
+
+        # @group Registering objects
+
+        def register_docstring(object, docstring = nil, stmt = nil)
+          super(object, docstring, stmt) if docstring
+        end
+
+        def register_file_info(object, file = nil, line = nil, comments = nil)
+          super(object, file, line, comments) if file
+        end
+
+        def register_source(object, source = nil, type = nil)
+          super(object, source, type) if source
+        end
+
+        def register_visibility(object, visibility = nil)
+          super(object, visibility) if visibility
+        end
+
+        # @group Looking up Symbol and Var Values
+
+        def symbols
+          globals.cruby_symbols ||= {}
+        end
+
+        def override_comments
+          globals.cruby_override_comments ||= []
+        end
+
+        def namespace_for_variable(var)
+          return namespaces[var] if namespaces[var]
+          var = remove_var_prefix(var)
+          var.empty? ? nil : P(var)
+        end
+
+        def namespaces
+          globals.cruby_namespaces ||= {}
+        end
+
+        def processed_files
+          globals.cruby_processed_files ||= {}
+        end
+
+        # @group Parsing an Inner Block
+
+        def parse_block(opts = {})
+          return if !statement.block || statement.block.empty?
+          push_state(opts) do
+            parser.process(statement.block)
+          end
+        end
+
+        # @group Processing other files
+
+        def process_file(file, object)
+          file = File.cleanpath(File.relative_path(statement.file, file))
+          return if processed_files[file]
+          processed_files[file] = file
+          begin
+            log.debug "Processing embedded call to C source #{file}..."
+            globals.ordered_parser.files.delete(file) if globals.ordered_parser
+            parser.process(Parser::C::CParser.new(File.read(file), file).parse)
+          rescue Errno::ENOENT
+            log.warn "Missing source file `#{file}' when parsing #{object}"
+          end
+        end
+
+        # @endgroup
+
+        private
+
+        def remove_var_prefix(var)
+          var.gsub(/^rb_[mc]|^[a-z_]+/, '')
+        end
+      end
+    end
+  end
+end