yard 0.6.8 → 0.7.0

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

@@ -1,7 +1,7 @@
 # Handles a conditional inside a method
 class YARD::Handlers::Ruby::MethodConditionHandler < YARD::Handlers::Ruby::Base
   handles :if_mod, :unless_mod
-  
+
   process do
     parse_block(statement.then_block, :owner => owner)
   end

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

@@ -1,7 +1,7 @@
 # Handles a method definition
 class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
   handles :def, :defs
-  
+
   process do
     nobj = namespace
     mscope = scope
@@ -19,28 +19,28 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
       args = format_args(statement[1])
       blk = statement[2]
     end
-    
+
     nobj = P(namespace, nobj.value) while nobj.type == :constant
-    obj = register MethodObject.new(nobj, meth, mscope) do |o| 
-      o.visibility = visibility 
+    obj = register MethodObject.new(nobj, meth, mscope) do |o|
+      o.visibility = visibility
       o.source = statement.source
       o.signature = method_signature(meth)
       o.explicit = true
       o.parameters = args
     end
-    
+
     # delete any aliases referencing old method
     nobj.aliases.each do |aobj, name|
       next unless name == obj.name
       nobj.aliases.delete(aobj)
     end if nobj.is_a?(NamespaceObject)
-    
+
     if mscope == :instance && meth == "initialize"
       unless obj.has_tag?(:return)
-        obj.docstring.add_tag(YARD::Tags::Tag.new(:return, 
+        obj.docstring.add_tag(YARD::Tags::Tag.new(:return,
           "a new instance of #{namespace.name}", namespace.name.to_s))
       end
-    elsif mscope == :class && obj.docstring.blank? && %w(inherited included 
+    elsif mscope == :class && obj.docstring.blank? && %w(inherited included
         extended method_added method_removed method_undefined).include?(meth)
       obj.docstring.add_tag(YARD::Tags::Tag.new(:private, nil))
     elsif meth.to_s =~ /\?$/
@@ -50,7 +50,7 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
         obj.docstring.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
       end
     end
-    
+
     if obj.has_tag?(:option)
       # create the options parameter if its missing
       obj.tags(:option).each do |option|
@@ -61,7 +61,7 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
         end
       end
     end
-    
+
     if info = obj.attr_info
       if meth.to_s =~ /=$/ # writer
         info[:write] = obj if info[:read]
@@ -69,10 +69,10 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
         info[:read] = obj if info[:write]
       end
     end
-    
+
     parse_block(blk, :owner => obj) # mainly for yield/exceptions
   end
-  
+
   def format_args(args)
     args = args.jump(:params)
     params = []
@@ -83,7 +83,7 @@ class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
     params << ["&" + args.block_param.source, nil] if args.block_param
     params
   end
-  
+
   def method_signature(method_name)
     if statement[1]
       "def #{method_name}(#{statement[1].jump(:params).source})"

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

@@ -1,8 +1,8 @@
 # Handles the 'include' statement to mixin a module in the instance scope
 class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
-  namespace_only
   handles method_call(:include)
-  
+  namespace_only
+
   process do
     errors = []
     statement.parameters(false).each do |mixin|
@@ -23,14 +23,14 @@ class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
   def process_mixin(mixin)
     raise YARD::Parser::UndocumentableError unless mixin.ref?
     raise YARD::Parser::UndocumentableError if mixin.first.type == :ident
-    
+
     case obj = Proxy.new(namespace, mixin.source)
     when Proxy
       obj.type = :module
     when ConstantObject # If a constant is included, use its value as the real object
       obj = Proxy.new(namespace, obj.value)
     end
-    
+
     namespace.mixins(scope).unshift(obj) unless namespace.mixins(scope).include?(obj)
   end
 end

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

@@ -1,7 +1,8 @@
 # Handles the declaration of a module
 class YARD::Handlers::Ruby::ModuleHandler < YARD::Handlers::Ruby::Base
   handles :module
-  
+  namespace_only
+
   process do
     modname = statement[0].source
     mod = register ModuleObject.new(namespace, modname)

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

@@ -1,8 +1,8 @@
 # Sets visibility of a constant (class, module, const)
 class YARD::Handlers::Ruby::PrivateConstantHandler < YARD::Handlers::Ruby::Base
-  namespace_only
   handles method_call(:private_constant)
-  
+  namespace_only
+
   process do
     errors = []
     statement.parameters.each do |param|
@@ -18,9 +18,9 @@ class YARD::Handlers::Ruby::PrivateConstantHandler < YARD::Handlers::Ruby::Base
       raise UndocumentableError, "private constant#{msg} for #{namespace.path}"
     end
   end
-  
+
   private
-  
+
   def privatize_constant(node)
     if node.literal? || (node.type == :var_ref && node[0].type == :const)
       node = node.jump(:tstring_content, :const)

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

@@ -1,9 +1,9 @@
 # Helper methods to parse @attr_* tags on a class.
-# 
+#
 # @since 0.5.6
 module YARD::Handlers::Ruby::StructHandlerMethods
   include YARD::CodeObjects
-  
+
   # Extracts the user's defined @member tag for a given class and its member. Returns
   # nil if the user did not define a @member tag for this struct entry.
   #
@@ -17,14 +17,14 @@ module YARD::Handlers::Ruby::StructHandlerMethods
   end
 
   # Retrieves all members defined in @attr* tags
-  # 
+  #
   # @param [ClassObject] klass the class with the attributes
   # @return [Array<String>] the list of members defined as attributes on the class
   def members_from_tags(klass)
     tags = klass.tags(:attr) + klass.tags(:attr_reader) + klass.tags(:attr_writer)
     tags.map {|t| t.name }.uniq
   end
-  
+
   # Determines whether to create an attribute method based on the class's
   # tags.
   #
@@ -38,7 +38,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
     return !member_tag_for_member(klass, member, :write) if type == :read
     return !member_tag_for_member(klass, member, :read)
   end
-  
+
   # Gets the return type for the member in a nicely formatted string. Used
   # to be injected into auto-generated docstrings.
   #
@@ -49,7 +49,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
   def return_type_from_tag(member_tag)
     (member_tag && member_tag.types) ? member_tag.types : "Object"
   end
-  
+
   # Creates the auto-generated docstring for the getter method of a struct's
   # member. This is used so the generated documentation will look just like that
   # of an attribute defined using attr_accessor.
@@ -64,7 +64,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
     new_method.docstring.replace(getter_doc_text)
     new_method.docstring.add_tag YARD::Tags::Tag.new(:return, "the current value of #{member}", return_type)
   end
-  
+
   # Creates the auto-generated docstring for the setter method of a struct's
   # member. This is used so the generated documentation will look just like that
   # of an attribute defined using attr_accessor.
@@ -80,7 +80,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
     new_method.docstring.add_tag YARD::Tags::Tag.new(:param, "the value to set the attribute #{member} to.", return_type, "value")
     new_method.docstring.add_tag YARD::Tags::Tag.new(:return, "the newly set value", return_type)
   end
-  
+
   # Creates and registers a class object with the given name and superclass name.
   # Returns it for further use.
   #
@@ -93,7 +93,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
       o.superclass.type = :class if o.superclass.is_a?(Proxy)
     end
   end
-  
+
   # Creates the setter (writer) method and attaches it to the class as an attribute.
   # Also sets up the docstring to prettify the documentation output.
   #
@@ -110,7 +110,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
     add_writer_tags(klass, new_meth, member)
     klass.attributes[:instance][member][:write] = new_meth
   end
-  
+
   # Creates the getter (reader) method and attaches it to the class as an attribute.
   # Also sets up the docstring to prettify the documentation output.
   #
@@ -124,7 +124,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
     add_reader_tags(klass, new_meth, member)
     klass.attributes[:instance][member][:read] = new_meth
   end
-  
+
   # Creates the given member methods and attaches them to the given ClassObject.
   #
   # @param [ClassObject] klass the class to generate attributes for

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

@@ -4,7 +4,7 @@ class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
   handles method_call(:protected)
   handles method_call(:public)
   namespace_only
-  
+
   process do
     return if (ident = statement.jump(:ident)) == statement
     case statement.type

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

@@ -1,30 +1,30 @@
 # Handles 'yield' calls
 class YARD::Handlers::Ruby::YieldHandler < YARD::Handlers::Ruby::Base
   handles :yield, :yield0
-  
+
   process do
     return unless owner.is_a?(MethodObject) # Only methods yield
     return if owner.has_tag? :yield         # Don't override yield tags
     return if owner.has_tag? :yieldparam    # Same thing.
 
     yieldtag = YARD::Tags::Tag.new(:yield, "", [])
-    
+
     if statement.type == :yield
       statement.jump(:list).children.each do |item|
         if item == s(:var_ref, s(:kw, "self"))
           yieldtag.types << '_self'
-          owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam, 
+          owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam,
             "the object that the method was called on", owner.namespace.path, '_self')
         elsif item == s(:zsuper)
           yieldtag.types << '_super'
-          owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam, 
+          owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam,
             "the result of the method from the superclass", nil, '_super')
         else
           yieldtag.types << item.source
         end
       end
     end
-    
+
     owner.docstring.add_tag(yieldtag) unless yieldtag.types.empty?
   end
 end

data/lib/yard/logging.rb

@@ -6,13 +6,13 @@ module YARD
   class Logger < ::Logger
     attr_writer :show_backtraces
     def show_backtraces; @show_backtraces || level == DEBUG end
-    
+
     # The logger instance
     # @return [Logger] the logger instance
     def self.instance(pipe = STDERR)
       @logger ||= new(pipe)
     end
-    
+
     # Creates a new logger
     def initialize(*args)
       super
@@ -20,27 +20,27 @@ module YARD
       self.level = WARN
       self.formatter = method(:format_log)
     end
-    
+
     # Changes the debug level to DEBUG if $DEBUG is set
     # and writes a debugging message.
     def debug(*args)
       self.level = DEBUG if $DEBUG
       super
     end
-    
+
     # Prints the backtrace +exc+ to the logger as error data.
-    # 
+    #
     # @param [Array<String>] exc the backtrace list
     # @return [void]
     def backtrace(exc)
       return unless show_backtraces
       error "#{exc.class.class_name}: #{exc.message}"
-      error "Stack trace:" + 
+      error "Stack trace:" +
         exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n"
     end
-    
+
     # Sets the logger level for the duration of the block
-    # 
+    #
     # @example
     #   log.enter_level(Logger::ERROR) do
     #     YARD.parse_string "def x; end"
@@ -48,14 +48,14 @@ module YARD
     # @param [Fixnum] new_level the logger level for the duration of the block.
     #   values can be found in Ruby's Logger class.
     # @yield the block with the logger temporarily set to +new_level+
-    def enter_level(new_level = level, &block) 
+    def enter_level(new_level = level, &block)
       old_level, self.level = level, new_level
       yield
       self.level = old_level
     end
-    
+
     private
-    
+
     # Log format (from Logger implementation). Used by Logger internally
     def format_log(sev, time, prog, msg)
       "[#{sev.downcase}]: #{msg}\n"

data/lib/yard/parser/base.rb

@@ -1,12 +1,12 @@
 module YARD
   module Parser
     # Represents the abstract base parser class that parses source code in
-    # a specific way. A parser should implement {#parse}, {#tokenize} and 
+    # a specific way. A parser should implement {#parse}, {#tokenize} and
     # {#enumerator}.
-    # 
+    #
     # == Registering a Custom Parser
     # To register a parser, see {SourceParser.register_parser_type}
-    # 
+    #
     # @abstract
     # @see #parse
     # @see #tokenize
@@ -17,7 +17,7 @@ module YARD
       def self.parse(source, filename = nil)
         new(source, filename).parse
       end
-      
+
       # This default constructor does nothing. The subclass is responsible for
       # storing the source contents and filename if they are required.
       # @param [String] source the source contents
@@ -25,25 +25,25 @@ module YARD
       def initialize(source, filename)
         raise NotImplementedError, "invalid parser implementation"
       end
-      
+
       # This method should be implemented to parse the source and return itself.
       # @abstract
       # @return [Base] this method should return itself
       def parse
         raise NotImplementedError, "#{self.class} must implement #parse"
       end
-      
+
       # This method should be implemented to tokenize given source
       # @abstract
       # @return [Array] a list/tree of lexical tokens
       def tokenize
         raise NotImplementedError, "#{self.class} does not support tokenization"
       end
-      
+
       # This method should be implemented to return a list of semantic tokens
       # representing the source code to be post-processed. Otherwise the method
       # should return nil.
-      # 
+      #
       # @abstract
       # @return [Array] a list of semantic tokens representing the source code
       #   to be post-processed

data/lib/yard/parser/c_parser.rb

@@ -10,7 +10,7 @@ module YARD
         @namespaces = {}
         @content = clean_source(source)
       end
-      
+
       def parse
         parse_modules
         parse_classes
@@ -18,19 +18,19 @@ module YARD
         parse_constants
         parse_includes
       end
-      
+
       # @since 0.5.6
       def tokenize
         raise NotImplementedError, "no tokenization support for C/C++ files"
       end
-      
+
       private
-      
+
       # @since 0.5.3
       def remove_var_prefix(var)
         var.gsub(/^rb_[mc]|^[a-z_]+/, '')
       end
-      
+
       def ensure_loaded!(object, max_retries = 1)
         return if object.is_a?(CodeObjects::RootObject)
         unless CONTINUATIONS_SUPPORTED
@@ -41,11 +41,11 @@ module YARD
           end
           raise NamespaceMissingError, object
         end
-        
+
         retries = 0
         context = callcc {|c| c }
-        retries += 1 
-        
+        retries += 1
+
         if object.is_a?(CodeObjects::Proxy)
           if retries <= max_retries
             log.debug "Missing object #{object} in file `#{@file}', moving it to the back of the line."
@@ -60,7 +60,7 @@ module YARD
         ensure_loaded!(namespace)
         obj = CodeObjects::ModuleObject.new(namespace, mod_name)
         obj.add_file(@file)
-        find_namespace_docstring(obj)      
+        find_namespace_docstring(obj)
         @namespaces[var_name] = obj
       end
 
@@ -71,17 +71,16 @@ module YARD
         obj = CodeObjects::ClassObject.new(namespace, class_name)
         obj.superclass = @namespaces[parent] || remove_var_prefix(parent) if parent
         obj.add_file(@file)
-        find_namespace_docstring(obj)      
+        find_namespace_docstring(obj)
         @namespaces[var_name] = obj
       end
-      
-      # @todo Handle +source_file+
+
       def handle_method(scope, var_name, name, func_name, source_file = nil)
         case scope
         when "singleton_method", "module_function"; scope = :class
         else; scope = :instance
         end
-        
+
         namespace = @namespaces[var_name] || P(remove_var_prefix(var_name))
         ensure_loaded!(namespace)
         obj = CodeObjects::MethodObject.new(namespace, name, scope)
@@ -89,9 +88,19 @@ module YARD
         obj.parameters = []
         obj.docstring.add_tag(YARD::Tags::Tag.new(:return, '', 'Boolean')) if name =~ /\?$/
         obj.source_type = :c
-        find_method_body(obj, func_name)
+
+        content = nil
+        begin
+          content = File.read(source_file) if source_file
+        rescue Errno::ENOENT
+          path = "#{namespace}#{scope == :instance ? '#' : '.'}#{name}"
+          log.warn "Missing source file `#{source_file}' when parsing #{path}"
+        ensure
+          content ||= @content
+        end
+        find_method_body(obj, func_name, content)
       end
-      
+
       def handle_constants(type, var_name, const_name, definition)
         namespace = @namespaces[var_name]
         obj = CodeObjects::ConstantObject.new(namespace, const_name)
@@ -118,7 +127,7 @@ module YARD
 
         obj.docstring = comment
       end
-      
+
       def find_namespace_docstring(object)
         comment = nil
         if @content =~ %r{((?>/\*.*?\*/\s+))
@@ -129,7 +138,7 @@ module YARD
         end
         object.docstring = parse_comments(object, comment) if comment
       end
-      
+
       def find_constant_docstring(object, type, const_name)
         comment = if @content =~ %r{((?>^\s*/\*.*?\*/\s+))
                        rb_define_#{type}\((?:\s*(\w+),)?\s*"#{const_name}"\s*,.*?\)\s*;}xmi
@@ -141,7 +150,7 @@ module YARD
         end
         object.docstring = parse_comments(object, comment) if comment
       end
-      
+
       def find_method_body(object, func_name, content = @content)
         case content
         when %r"((?>/\*.*?\*/\s*))(?:(?:static|SWIGINTERN)\s+)?(?:intern\s+)?VALUE\s+#{func_name}
@@ -188,7 +197,7 @@ module YARD
           nil
         end
       end
-      
+
       def parse_comments(object, comments)
         spaces = nil
         comments = remove_private_comments(comments)
@@ -207,7 +216,7 @@ module YARD
         comments = parse_callseq(object, comments)
         comments.join("\n")
       end
-      
+
       def parse_callseq(object, comments)
         return comments unless comments[0] =~ /\Acall-seq:\s*(\S.+)?/
         if $1
@@ -247,10 +256,10 @@ module YARD
           overloads << "  @yield [#{blkparams}]" if blk
           overloads << "  @return [#{types.join(', ')}]" unless types.empty?
         end
-        
+
         comments + [""] + overloads
       end
-      
+
       def parse_types(object, types)
         if types =~ /true or false/
           ["Boolean"]
@@ -288,7 +297,7 @@ module YARD
           end.compact
         end
       end
-      
+
       def parse_modules
         @content.scan(/(\w+)\s* = \s*rb_define_module\s*
             \(\s*"(\w+)"\s*\)/mx) do |var_name, class_name|
@@ -303,7 +312,7 @@ module YARD
           handle_module(var_name, class_name, in_module)
         end
       end
-      
+
       def parse_classes
         # The '.' lets us handle SWIG-generated files
         @content.scan(/([\w\.]+)\s* = \s*(?:rb_define_class|boot_defclass)\s*
@@ -323,7 +332,7 @@ module YARD
           handle_class(var_name, class_name, parent, in_module)
         end
       end
-      
+
       def parse_methods
         @content.scan(%r{rb_define_
                        (
@@ -357,7 +366,7 @@ module YARD
           handle_method("method", "rb_mKernel", name, func_name, source_file)
         end
       end
-      
+
       def parse_includes
         @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |klass, mod|
           if klass = @namespaces[klass]
@@ -366,7 +375,7 @@ module YARD
           end
         end
       end
-      
+
       def parse_constants
         @content.scan(%r{\Wrb_define_
                        (
@@ -384,20 +393,20 @@ module YARD
           handle_constants(type, var_name, const_name, definition)
         end
       end
-      
+
       private
-      
+
       def clean_source(source)
         source = handle_ifdefs_in(source)
         source = handle_tab_width(source)
         source = remove_commented_out_lines(source)
         source
       end
-      
+
       def handle_ifdefs_in(body)
         body.gsub(/^#ifdef HAVE_PROTOTYPES.*?#else.*?\n(.*?)#endif.*?\n/m, '\1')
       end
-      
+
       def handle_tab_width(body)
         if /\t/ =~ body
           tab_width = 4
@@ -409,11 +418,11 @@ module YARD
           body
         end
       end
-        
+
       def remove_commented_out_lines(body)
         body.gsub(%r{//.*rb_define_}, '//')
       end
-      
+
       def remove_private_comments(comment)
          comment = comment.gsub(/\/?\*--\n(.*?)\/?\*\+\+/m, '')
          comment = comment.sub(/\/?\*--\n.*/m, '')