yard 0.2.2 → 0.2.3

data/lib/yard/generators/method_listing_generator.rb

@@ -69,9 +69,9 @@ module YARD
       # 
       def included_meths_by_module
         all_meths = current_object.included_meths(:scope => scope, :visibility => visibility)
-        current_object.mixins.each do |mixin|
+        current_object.mixins(scope).each do |mixin|
           next if mixin.is_a?(CodeObjects::Proxy)
-          meths = mixin.meths(meths_opts).select {|c| all_meths.include?(c) }
+          meths = mixin.meths(meths_opts.merge(:scope => :instance)).select {|c| all_meths.include?(c) }
           remove_ignored_meths!(meths)
           next if meths.empty?
           yield(mixin, meths)
@@ -102,4 +102,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/generators/mixins_generator.rb

@@ -1,15 +1,21 @@
 module YARD
   module Generators
     class MixinsGenerator < Base
+      attr_reader :scope
       before_generate :has_mixins?
+
+      def initialize(*args)
+        super
+        @scope = options[:scope]
+      end
       
       def sections_for(object) [:header] end
         
       protected
       
       def has_mixins?(object)
-        !object.mixins.empty?
+        !object.mixins(@scope).empty?
       end
     end
   end
-end
+end

data/lib/yard/generators/module_generator.rb

@@ -7,7 +7,8 @@ module YARD
         [
           :header,
           [
-            G(MixinsGenerator), 
+            G(MixinsGenerator, :scope => :class),
+            G(MixinsGenerator, :scope => :instance),
             G(DocstringGenerator), 
             G(AttributesGenerator), 
             G(ConstantsGenerator),
@@ -19,4 +20,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/generators/overloads_generator.rb

@@ -0,0 +1,20 @@
+module YARD
+  module Generators
+    class OverloadsGenerator < Base
+      before_generate :has_overloads?
+
+      def sections_for(object)
+        [
+          :header,
+          [G(MethodGenerator)]
+        ]
+      end
+
+      protected
+
+      def has_overloads?(object)
+        object.tags(:overload).size > 1
+      end
+    end
+  end
+end

data/lib/yard/generators/quick_doc_generator.rb

@@ -5,14 +5,8 @@ module YARD
         case object
         when CodeObjects::MethodObject
           [
-            :header, 
-            [
-              G(DeprecatedGenerator), 
-              G(DocstringGenerator), 
-              G(MethodSignatureGenerator), 
-              G(TagsGenerator), 
-              G(SourceGenerator)
-            ]
+            :header,
+            [G(MethodGenerator)]
           ]
         when CodeObjects::NamespaceObject
           [
@@ -28,4 +22,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/generators/root_generator.rb

@@ -0,0 +1,32 @@
+module YARD
+  module Generators
+    class RootGenerator < Base
+      before_generate :is_root?
+      before_generate :has_data?
+      
+      def sections_for(object) 
+        [
+          :header,
+          [
+            G(MixinsGenerator, :scope => :class),
+            G(MixinsGenerator, :scope => :instance),
+            G(ConstantsGenerator),
+            G(VisibilityGroupGenerator, :visibility => :public),
+            G(VisibilityGroupGenerator, :visibility => :protected),
+            G(VisibilityGroupGenerator, :visibility => :private)
+          ]
+        ]
+      end
+      
+      private
+      
+      def has_data?(object)
+        object.meths.size > 0 || object.constants.size > 0
+      end
+      
+      def is_root?(object)
+        object == Registry.root
+      end
+    end
+  end
+end

data/lib/yard/generators/source_generator.rb

@@ -1,26 +1,11 @@
 module YARD
   module Generators
     class SourceGenerator < Base
+      include Helpers::MethodHelper
+      
       def sections_for(object) 
         [:main] if object.source
       end
-      
-      protected
-      
-      def format_lines(object)
-        i = -1
-        object.source.split(/\n/).map { object.line + (i += 1) }.join("\n")
-      end
-      
-      def format_code(object, show_lines = false)
-        i = -1
-        lines = object.source.split(/\n/)
-        longestline = (object.line + lines.size).to_s.length
-        lines.map do |line| 
-          lineno = object.line + (i += 1)
-          (" " * (longestline - lineno.to_s.length)) + lineno.to_s + "    " + line
-        end.join("\n")
-      end
     end
   end
 end

data/lib/yard/generators/tags_generator.rb

@@ -1,20 +1,26 @@
 module YARD
   module Generators
     class TagsGenerator < Base
-      before_section :header, :has_tags?
+      before_section :header,  :has_tags?
+      before_section :option, :has_options?
+      before_section :param, :has_params?
       
       def sections_for(object)
-        [:header, [:param, :yieldparam, :return, :raise, :author, :version, :since, :see]]
+        [:header, [:example, :param, :yield, :yieldparam, :yieldreturn, :return, :raise, :todo, :author, :version, :since, :see]]
       end
       
-      def param(object)
-        render_tags :param
+      def yield(object)
+        render_tags :yield
       end
       
       def yieldparam(object)
         render_tags :yieldparam
       end
-      
+
+      def yieldreturn(object)
+        render_tags :yieldreturn
+      end
+
       def return(object)
         render_tags :return
       end
@@ -37,14 +43,36 @@ module YARD
       
       protected
       
+      def has_params?(object)
+        object.is_a?(CodeObjects::MethodObject) && tags_by_param(object).size > 0
+      end
+      
       def has_tags?(object)
         object.tags.size > 0
       end
       
+      def has_options?(object)
+        object.has_tag?(:option)
+      end
+      
       def render_tags(name, opts = {})
         opts = { :name => name }.update(opts)
         render(current_object, 'tags', opts)
       end
+      
+      def tags_by_param(object)
+        cache = {}
+        [:param, :option].each do |sym|
+          object.tags(sym).each do |t|
+            cache[t.name.to_s] = t
+          end
+        end
+        
+        object.parameters.map do |p|
+          name = p.first.to_s
+          cache[name] || cache[name[/^[*&](\w+)$/, 1]]
+        end.compact
+      end
     end
   end
-end
+end

data/lib/yard/generators/uml_generator.rb

@@ -60,22 +60,32 @@ module YARD
       
       def process_objects(object)
         @objects[object.path] = object
-        @objects[object.superclass.path] = object.superclass if object.is_a?(CodeObjects::ClassObject)
+        @objects[object.superclass.path] = object.superclass if object.is_a?(CodeObjects::ClassObject) && object.superclass
         object.mixins.each {|o| @objects[o.path] = o }
 
         namespaces(object).each {|o| process_objects(o) }
       end
       
-      def method_list(object)
+      def method_list(object, attributes = false)
         vissort = lambda {|vis| vis == :public ? 'a' : (vis == :protected ? 'b' : 'c') }
         
-        object.meths(:inherited => false, :included => false, :visibility => options[:visibility]).reject do |o|
-          o.is_attribute?
-        end.sort_by {|o| "#{o.scope}#{vissort.call(o.visibility)}#{o.name}" }
+        meths = object.meths(:inherited => false, :included => false, :visibility => options[:visibility])
+        meths = remove_overriden_meths(object, meths)
+        meths = meths.select {|o| attributes ? o.is_attribute? : !o.is_attribute? }
+        meths = meths.reject {|o| o.is_alias? }
+        meths = meths.sort_by {|o| "#{o.scope}#{vissort.call(o.visibility)}#{o.name}" }
       end
       
       private
       
+      def remove_overriden_meths(object, meth_list)
+        object.inheritance_tree(true)[1..-1].each do |sclass|
+          next if CodeObjects::Proxy === sclass
+          meth_list.reject! {|o| sclass.child(:scope => o.scope, :name => o.name) }
+        end
+        meth_list
+      end
+      
       def tidy(data)
         indent = 0
         data.split(/\n/).map do |line|
@@ -89,4 +99,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/handlers/base.rb

@@ -1,6 +1,9 @@
 module YARD
   module Handlers
-    class UndocumentableError < Exception; end
+    class NamespaceMissingError < Parser::UndocumentableError
+      attr_accessor :object
+      def initialize(object) @object = object end
+    end
     
     # = Handlers 
     # 
@@ -33,7 +36,7 @@ module YARD
     # A Handler is automatically registered when it is subclassed from the
     # base class. The only other thing that needs to be done is to specify
     # which statement the handler will process. This is done with the +handles+
-    # declaration, taking either a {Parser::RubyToken}, {String} or {Regexp}.
+    # declaration, taking either a {Parser::Ruby::Legacy::RubyToken}, {String} or `Regexp`.
     # Here is a simple example which processes module statements.
     # 
     #   class MyModuleHandler < YARD::Handlers::Base
@@ -53,10 +56,10 @@ module YARD
     # 
     # === +statement+ Attribute 
     # 
-    # The +statement+ attribute pertains to the {Parser::Statement} object
+    # The +statement+ attribute pertains to the {Parser::Ruby::Legacy::Statement} object
     # containing a set of tokens parsed in by the parser. This is the main set
     # of data to be analyzed and processed. The comments attached to the statement
-    # can be accessed by the {Parser::Statement#comments} method, but generally
+    # can be accessed by the {Parser::Ruby::Legacy::Statement#comments} method, but generally
     # the data to be processed will live in the +tokens+ attribute. This list
     # can be converted to a +String+ using +#to_s+ to parse the data with
     # regular expressions (or other text processing mechanisms), if needed.
@@ -131,14 +134,11 @@ module YARD
     # @see #parse_block
     #
     class Base 
-      attr_accessor :__context__
-
       # For accessing convenience, eg. "MethodObject" 
       # instead of the full qualified namespace
       include YARD::CodeObjects
       
-      # For tokens like TkDEF, TkCLASS, etc.
-      include YARD::Parser::RubyToken
+      include Parser
       
       class << self
         def clear_subclasses
@@ -146,7 +146,7 @@ module YARD
         end
         
         def subclasses
-          @@subclasses || []
+          @@subclasses ||= []
         end
 
         def inherited(subclass)
@@ -164,7 +164,7 @@ module YARD
         # the handlers, otherwise the same code will be parsed
         # multiple times and slow YARD down.
         # 
-        # @param [Parser::RubyToken, String, Regexp] match
+        # @param [Parser::RubyToken, Symbol, String, Regexp] matches
         #   statements that match the declaration will be
         #   processed by this handler. A {String} match is 
         #   equivalent to a +/\Astring/+ regular expression 
@@ -172,19 +172,24 @@ module YARD
         #   token matches match only the first token of the
         #   statement.
         # 
-        def handles(match)
-          @handler = match
+        def handles(*matches)
+          (@handlers ||= []).push(*matches)
         end
         
-        def handles?(tokens)
-          case @handler
-          when String
-            tokens.first.text == @handler
-          when Regexp
-            tokens.to_s =~ @handler ? true : false
-          else
-            @handler == tokens.first.class 
-          end
+        def handles?(statement)
+          raise NotImplementedError, "override #handles? in a subclass"
+        end
+        
+        def handlers
+          @handlers ||= []
+        end
+        
+        def namespace_only
+          @namespace_only = true
+        end
+        
+        def namespace_only?
+          @namespace_only ? true : false
         end
       end
 
@@ -213,11 +218,50 @@ module YARD
         raise NotImplementedError, "#{self} did not implement a #process method for handling."
       end
       
+      def parse_block(*args)
+        raise NotImplementedError, "#{self} did not implement a #parse_block method for handling"
+      end
+      
       protected
       
       attr_reader :parser, :statement
       attr_accessor :owner, :namespace, :visibility, :scope
       
+      def owner; parser.owner end
+      def owner=(v) parser.owner=(v) end
+      def namespace; parser.namespace end
+      def namespace=(v); parser.namespace=(v) end
+      def visibility; parser.visibility end
+      def visibility=(v); parser.visibility=(v) end
+      def scope; parser.scope end
+      def scope=(v); parser.scope=(v) end
+      
+      def push_state(opts = {}, &block)
+        opts = {
+          :namespace => nil,
+          :scope => :instance,
+          :owner => nil
+        }.update(opts)
+
+        if opts[:namespace]
+          ns, vis, sc = namespace, visibility, scope
+          self.namespace = opts[:namespace]
+          self.visibility = :public
+          self.scope = opts[:scope]
+        end
+
+        oldowner, self.owner = self.owner, opts[:owner] ? opts[:owner] : namespace
+        yield
+        self.owner = oldowner
+
+        if opts[:namespace]
+          self.namespace = ns
+          self.owner = namespace
+          self.visibility = vis
+          self.scope = sc
+        end
+      end
+      
       # Do some post processing on a list of code objects. 
       # Adds basic attributes to the list of objects like 
       # the filename, line number, {CodeObjects::Base#dynamic},
@@ -234,7 +278,11 @@ module YARD
         objects.flatten.each do |object|
           next unless object.is_a?(CodeObjects::Base)
           
-          ensure_namespace_loaded!(object)
+          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
           #   
@@ -243,266 +291,53 @@ module YARD
           # as the block for #register. We need to make sure this gets to the object.
           yield(object) if block_given? 
           
-          # Add file and line number, but for class/modules this is 
-          # only done if there is a docstring for this specific definition.
-          if (object.is_a?(NamespaceObject) && statement.comments) || !object.is_a?(NamespaceObject)
-            object.file = parser.file
-            object.line = statement.tokens.first.line_no
-          elsif object.is_a?(NamespaceObject) && !statement.comments
-            object.file ||= parser.file
-            object.line ||= statement.tokens.first.line_no
-          end
-          
+          object.add_file(parser.file, statement.line, statement.comments)
+
           # Add docstring if there is one.
           object.docstring = statement.comments if statement.comments
           
           # Add source only to non-class non-module objects
           unless object.is_a?(NamespaceObject)
-            object.source ||= statement 
+            object.source ||= statement
           end
           
-          # Make it dynamic if it's owner is not it's namespace.
+          # 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
         end
         objects.size == 1 ? objects.first : objects
       end
-      
-      def parse_block(opts = nil)
-        opts = {
-          :namespace => nil,
-          :scope => :instance,
-          :owner => nil
-        }.update(opts || {})
-        
-        if opts[:namespace]
-          ns, vis, sc = namespace, visibility, scope
-          self.namespace = opts[:namespace]
-          self.visibility = :public
-          self.scope = opts[:scope]
-        end
-
-        self.owner = opts[:owner] ? opts[:owner] : namespace
-        parser.parse(statement.block) if statement.block
-        
-        if opts[:namespace]
-          self.namespace = ns
-          self.owner = namespace
-          self.visibility = vis
-          self.scope = sc
-        end
-      end
 
-      def owner; @parser.owner end
-      def owner=(v) @parser.owner=(v) end
-      def namespace; @parser.namespace end
-      def namespace=(v); @parser.namespace=(v) end
-      def visibility; @parser.visibility end
-      def visibility=(v); @parser.visibility=(v) end
-      def scope; @parser.scope end
-      def scope=(v); @parser.scope=(v) end
-      
-      def ensure_namespace_loaded!(object, max_retries = 1)
+      def ensure_loaded!(object, max_retries = 1)
         unless parser.load_order_errors
-          return object.parent.is_a?(Proxy) ? load_order_warn(object.parent) : nil
+          if object.is_a?(Proxy)
+            raise NamespaceMissingError, object
+          else
+            nil
+          end
         end
         
-        raise NotImplementedError if RUBY_PLATFORM =~ /java/ 
-        return unless object.parent.is_a?(Proxy)
+        if RUBY_PLATFORM =~ /java/ 
+          log.warn "JRuby does not implement Kernel#callcc and cannot load files in order. You must specify the correct order manually."
+          raise NamespaceMissingError, object
+        end
         
         retries, context = 0, nil
         callcc {|c| context = c }
 
         retries += 1 
         
-        if object.parent.is_a?(Proxy)
+        if object.is_a?(Proxy)
           if retries <= max_retries
             log.debug "Missing object #{object.parent} in file `#{parser.file}', moving it to the back of the line."
             raise Parser::LoadOrderError, context
-          end
-
-          if retries > max_retries && !object.parent.is_a?(Proxy) && !BUILTIN_ALL.include?(object.path)
-            load_order_warn(object.parent)
+          else
+            raise NamespaceMissingError, object
           end
         else
           log.debug "Object #{object} successfully resolved. Adding item to #{object.parent}'s children"
-          object.namespace.children << object 
-        end
-
-      rescue NotImplementedError
-        log.warn "JRuby does not implement Kernel#callcc and cannot load files in order. You must specify the correct order manually."
-        load_order_warn(object.parent)
-      end
-      
-      def load_order_warn(object)
-        log.warn "The #{object.type} #{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." 
-        log.warn "You can correct this issue by loading the source file for this object before `#{parser.file}'"
-        log.warn 
-      end
-      
-      # The string value of a token. For example, the return value for the symbol :sym 
-      # would be :sym. The return value for a string "foo #{bar}" would be the literal 
-      # "foo #{bar}" without any interpolation. The return value of the identifier
-      # 'test' would be the same value: 'test'. Here is a list of common types and
-      # their return values:
-      # 
-      # @example 
-      #   tokval(TokenList.new('"foo"').first) => "foo"
-      #   tokval(TokenList.new(':foo').first) => :foo
-      #   tokval(TokenList.new('CONSTANT').first, RubyToken::TkId) => "CONSTANT"
-      #   tokval(TokenList.new('identifier').first, RubyToken::TkId) => "identifier"
-      #   tokval(TokenList.new('3.25').first) => 3.25
-      #   tokval(TokenList.new('/xyz/i').first) => /xyz/i
-      # 
-      # @param [Token] token The token of the class
-      # 
-      # @param [Array<Class<Token>>, Symbol] accepted_types
-      #   The allowed token types that this token can be. Defaults to [{TkVal}].
-      #   A list of types would be, for example, [{TkSTRING}, {TkSYMBOL}], to return
-      #   the token's value if it is either of those types. If +TkVal+ is accepted, 
-      #   +TkNode+ is also accepted.
-      # 
-      #   Certain symbol keys are allowed to specify multiple types in one fell swoop.
-      #   These symbols are:
-      #     :string       => +TkSTRING+, +TkDSTRING+, +TkDXSTRING+ and +TkXSTRING+
-      #     :attr         => +TkSYMBOL+ and +TkSTRING+
-      #     :identifier   => +TkIDENTIFIER, +TkFID+ and +TkGVAR+.
-      #     :number       => +TkFLOAT+, +TkINTEGER+
-      # 
-      # @return [Object] if the token is one of the accepted types, in its real value form.
-      #   It should be noted that identifiers and constants are kept in String form.
-      # @return [nil] if the token is not any of the specified accepted types
-      def tokval(token, *accepted_types)
-        accepted_types = [TkVal] if accepted_types.empty?
-        accepted_types.push(TkNode) if accepted_types.include? TkVal
-        
-        if accepted_types.include?(:attr)
-          accepted_types.push(TkSTRING, TkSYMBOL)
-        end
-
-        if accepted_types.include?(:string)
-          accepted_types.push(TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING)
-        end
-        
-        if accepted_types.include?(:identifier)
-          accepted_types.push(TkIDENTIFIER, TkFID, TkGVAR)
-        end
-
-        if accepted_types.include?(:number)
-          accepted_types.push(TkFLOAT, TkINTEGER)
-        end
-        
-        return unless accepted_types.any? {|t| t === token }
-        
-        case token
-        when TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING 
-          token.text[1..-2]
-        when TkSYMBOL
-          token.text[1..-1].to_sym
-        when TkFLOAT
-          token.text.to_f
-        when TkINTEGER
-          token.text.to_i
-        when TkREGEXP
-          token.text =~ /\A\/(.+)\/([^\/])\Z/
-          Regexp.new($1, $2)
-        when TkTRUE
-          true
-        when TkFALSE
-          false
-        when TkNIL
-          nil
-        else
-          token.text
-        end
-      end
-      
-      # Returns a list of symbols or string values from a statement. 
-      # The list must be a valid comma delimited list, and values 
-      # will only be returned to the end of the list only.
-      # 
-      # Example:
-      #   attr_accessor :a, 'b', :c, :d => ['a', 'b', 'c', 'd']
-      #   attr_accessor 'a', UNACCEPTED_TYPE, 'c' => ['a', 'c'] 
-      # 
-      # The tokval list of a {TokenList} of the above
-      # code would be the {#tokval} value of :a, 'b',
-      # :c and :d.
-      # 
-      # It should also be noted that this function stops immediately at
-      # any ruby keyword encountered:
-      #   "attr_accessor :a, :b, :c if x == 5"  => ['a', 'b', 'c']
-      # 
-      # @param [TokenList] tokenlist The list of tokens to process.
-      # @param [Array<Class<Token>>] accepted_types passed to {#tokval}
-      # @return [Array<String>] the list of tokvalues in the list.
-      # @return [Array<EMPTY>] if there are no symbols or Strings in the list 
-      # @see #tokval
-      def tokval_list(tokenlist, *accepted_types)
-        return [] unless tokenlist
-        out = [[]]
-        parencount, beforeparen = 0, 0
-        needcomma = false
-        seen_comma = true
-        tokenlist.each do |token|
-          tokval = tokval(token, *accepted_types)
-          parencond = !out.last.empty? && tokval != nil
-          #puts "#{seen_comma.inspect} #{parencount} #{token.class.class_name} #{out.inspect}"
-          case token
-          when TkCOMMA
-            if parencount == 0
-              out << [] unless out.last.empty?
-              needcomma = false
-              seen_comma = true
-            else
-              out.last << token.text if parencond
-            end
-          when TkLPAREN
-            if seen_comma
-              beforeparen += 1
-            else
-              parencount += 1
-              out.last << token.text if parencond
-            end
-          when TkRPAREN
-            if beforeparen > 0
-              beforeparen -= 1
-            else
-              out.last << token.text if parencount > 0 && tokval != nil
-              parencount -= 1
-            end
-          when TkLBRACE, TkLBRACK, TkDO
-            parencount += 1 
-            out.last << token.text if tokval != nil
-          when TkRBRACE, TkRBRACK, TkEND
-            out.last << token.text if tokval != nil
-            parencount -= 1
-          else
-            break if TkKW === token && ![TkTRUE, TkFALSE, TkSUPER, TkSELF, TkNIL].include?(token.class)
-            
-            seen_comma = false unless TkWhitespace === token
-            if parencount == 0
-              next if needcomma 
-              next if TkWhitespace === token
-              if tokval != nil
-                out.last << tokval
-              else
-                out.last.clear
-                needcomma = true
-              end 
-            elsif parencond
-              needcomma = true
-              out.last << token.text
-            end
-          end
-
-          if beforeparen == 0 && parencount < 0
-            break
-          end
         end
-        # Flatten any single element lists
-        out.map {|e| e.empty? ? nil : (e.size == 1 ? e.pop : e.flatten.join) }.compact
+        object
       end
     end
   end