yard 0.2.0

data/lib/handlers/all_handlers.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + '/code_object_handler'
+Dir[File.dirname(__FILE__) + '/*_handler.rb'].reject {|f| f =~ /code_object_handler\.rb$/ }.each {|file| require file }

data/lib/handlers/attribute_handler.rb

@@ -0,0 +1,46 @@
+class YARD::AttributeHandler < YARD::CodeObjectHandler
+  handles /\Aattr(_(reader|writer|accessor))?\b/
+  
+  def process
+    attr_type   = statement.tokens.first.text.to_sym
+    symbols     = eval("[" + statement.tokens[1..-1].to_s + "]")
+    read, write = true, false
+    
+    # Change read/write based on attr_reader/writer/accessor
+    case attr_type
+    when :attr
+      # In the case of 'attr', the second parameter (if given) isn't a symbol.
+      read = symbols.pop if symbols.size == 2
+    when :attr_accessor
+      write = true
+    when :attr_reader
+      # change nothing
+    when :attr_writer
+      read, write = false, true
+    end
+
+    # Add all attributes
+    symbols.each do |name| 
+      name = name.to_s
+      object[:attributes].update(name.to_s => { :read => read, :write => write })
+
+      # Show their methods as well
+      [name, "#{name}="].each do |method|
+        YARD::MethodObject.new(method, current_visibility, current_scope, object, statement.comments) do |obj|
+          if method.to_s.include? "="
+            src = "def #{method}(value)"
+            full_src = "#{src}\n  @#{name} = value\nend"
+            doc = "Sets the attribute +#{name}+\n@param value the value to set the attribute +#{name}+ to."
+          else
+            src = "def #{method}"
+            full_src = "#{src}\n  @#{name}\nend"
+            doc = "Returns the value of attribute +#{name}+"
+          end
+          obj.attach_source(src)
+          obj.attach_full_source(full_src)
+          obj.attach_docstring(doc)
+        end
+      end
+    end
+  end
+end

data/lib/handlers/class_handler.rb

@@ -0,0 +1,29 @@
+class YARD::ClassHandler < YARD::CodeObjectHandler
+  handles RubyToken::TkCLASS
+  
+  def process
+    words = statement.tokens.to_s.strip.split(/\s+/)
+    class_name, superclass = words[1], (words[3] || "Object")
+    if class_name == "<<"
+      if words[2] == "self"
+        class_name = nil
+      else
+        class_name = "Anonymous$#{class_name}"
+      end
+    end
+    
+    if class_name.nil?
+      # This is a class << self block. We change the scope to class level methods
+      # and reset the visibility to public, but we don't enter a new namespace.
+      scope, vis = current_namespace.attributes[:scope], current_visibility
+      current_visibility = :public
+      current_namespace.attributes[:scope] = :class
+      parse_block
+      current_namespace.attributes[:scope], current_visibility = scope, vis
+    else
+      class_name = move_to_namespace(class_name)
+      class_obj = YARD::ClassObject.new(class_name, superclass, object, statement.comments)
+      enter_namespace(class_obj) { parse_block }
+    end
+  end
+end

data/lib/handlers/class_variable_handler.rb

@@ -0,0 +1,9 @@
+class YARD::ClassVariableHandler < YARD::CodeObjectHandler
+  HANDLER_MATCH = /\A@@\S*\s*=\s*/m
+  handles HANDLER_MATCH
+  
+  def process
+    return unless object.is_a? YARD::CodeObjectWithMethods
+    YARD::ClassVariableObject.new(statement, object)
+  end
+end

data/lib/handlers/code_object_handler.rb

@@ -0,0 +1,104 @@
+class YARD::CodeObjectHandler
+  class << self
+    def subclasses
+      @@subclasses || []
+    end
+  
+    def inherited(subclass)
+      @@subclasses ||= []
+      @@subclasses << subclass
+    end
+  
+    def handles(token)
+      @handler = token
+    end
+  
+    def handles?(tokens)
+      case @handler
+      when String
+        tokens.first.text == @handler
+      when Regexp
+        tokens.to_s =~ @handler
+      else
+        @handler <= tokens.first.class
+      end
+    end
+  end
+  
+  attr_reader :parser, :statement
+  
+  def initialize(source_parser, stmt)
+    @parser = source_parser
+    @statement = stmt
+  end
+  
+  def process
+  end
+  
+  protected
+    def current_visibility
+      current_namespace.attributes[:visibility]
+    end
+
+    def current_visibility=(value)
+      current_namespace.attributes[:visibility] = value
+    end
+    
+    def current_scope
+      current_namespace.attributes[:scope]
+    end
+    
+    def current_scope=(value)
+      current_namespace.attributes[:scope] = value
+    end
+    
+    def object
+      current_namespace.object
+    end
+    
+    def attributes
+      current_namespace.attributes
+    end
+  
+    def current_namespace
+      parser.current_namespace
+    end
+  
+    def current_namespace=(value)
+      parser.current_namespace = value
+    end
+  
+    def enter_namespace(name, *args, &block)
+      namespace = parser.current_namespace
+      if name.is_a? YARD::CodeObject
+        self.current_namespace = YARD::NameStruct.new(name)
+        #object.add_child(name)
+        yield(name)
+      else
+        object.add_child(name, *args) do |obj| 
+          self.current_namespace = YARD::NameStruct.new(obj)
+          obj.attach_source(statement.tokens.to_s, parser.file, statement.tokens.first.line_no)
+          obj.attach_docstring(statement.comments) 
+          yield(obj)
+        end
+      end
+      self.current_namespace = namespace
+    end
+    
+    def move_to_namespace(namespace)
+      # If the class extends over a namespace, go to the proper object
+      if namespace.include? "::"
+        path = namespace.split("::") 
+        name = path.pop
+        path = path.join("::")
+        full_namespace = [object.path, path].compact.join("::").gsub(/^::/, '')
+        current_namespace.object = YARD::Namespace.find_or_create_namespace(full_namespace)
+        namespace = name
+      end
+      namespace
+    end
+    
+    def parse_block
+      parser.parse(statement.block) if statement.block
+    end
+end

data/lib/handlers/constant_handler.rb

@@ -0,0 +1,11 @@
+class YARD::ConstantHandler < YARD::CodeObjectHandler
+  HANDLER_MATCH = /\A[^@\$]\S*\s*=\s*/m
+  handles HANDLER_MATCH
+  
+  def process
+    return unless object.is_a? YARD::CodeObjectWithMethods
+    const, expr = *statement.tokens.to_s.split(/\s*=\s*/, 2)
+    #expr.gsub!(/\/s+/,' ')
+    obj = YARD::ConstantObject.new(const, object, statement)
+  end
+end

data/lib/handlers/exception_handler.rb

@@ -0,0 +1,20 @@
+class YARD::ExceptionHandler < YARD::CodeObjectHandler
+  handles 'raise'
+  
+  def process
+    tokens = statement.tokens.reject {|tk| [RubyToken::TkSPACE, RubyToken::TkLPAREN].include? tk }
+    from = tokens.each_with_index do |token, index|
+      break index if token.class == RubyToken::TkIDENTIFIER && token.text == 'raise'
+    end
+    if from.is_a? Fixnum
+      exception_class = tokens[(from+1)..-1].to_s[/^\s*(\S+?),?/, 1]
+      # RuntimeError for Strings or no parameter
+      exception_class = "RuntimeError" if exception_class =~ /^\"/ || exception_class.nil?
+      
+      # Only add the tag if it hasn't already been added (by exception class).
+      unless object.tags("raise").any? {|tag| tag.name == exception_class }
+        object.tags << YARD::TagLibrary.raise_tag(exception_class)
+      end
+    end
+  end
+end

data/lib/handlers/method_handler.rb

@@ -0,0 +1,27 @@
+class YARD::MethodHandler < YARD::CodeObjectHandler
+  handles RubyToken::TkDEF
+  
+  def process
+    stmt_nospace = statement.tokens.reject {|t| t.is_a? RubyToken::TkSPACE }
+    method_name, method_scope = stmt_nospace[1].text, current_scope
+    holding_object = object
+    
+    # Use the third token (after the period) if statement begins with a "Constant." or "self."
+    if [RubyToken::TkCOLON2,RubyToken::TkDOT].include?(stmt_nospace[2].class)
+      method_class = stmt_nospace[1].text
+      holding_object = YARD::Namespace.find_from_path(object.path, method_class)
+      holding_object = YARD::Namespace.find_or_create_namespace(method_class) if holding_object.nil?
+      method_name = stmt_nospace[3..-1].to_s[/\A(.+?)(?:\(|;|$)/,1]
+      method_scope = :class
+    end
+  
+    method_object = YARD::MethodObject.new(method_name, current_visibility, 
+                                           method_scope, holding_object, statement.comments)
+    enter_namespace(method_object) do |obj|
+      #puts "->\tMethod #{obj.path} (visibility: #{obj.visibility})"
+      # Attach better source code
+      obj.attach_source(statement, parser.file)
+      parse_block
+    end
+  end
+end

data/lib/handlers/mixin_handler.rb

@@ -0,0 +1,9 @@
+class YARD::MixinHandler < YARD::CodeObjectHandler
+  handles /\Ainclude\b/
+  
+  def process
+    return unless object.is_a? YARD::CodeObjectWithMethods
+    object.mixins.push eval(statement.tokens[1..-1].to_s).to_s
+    object.mixins.uniq!
+  end
+end

data/lib/handlers/module_handler.rb

@@ -0,0 +1,9 @@
+class YARD::ModuleHandler < YARD::CodeObjectHandler
+  handles RubyToken::TkMODULE
+  
+  def process
+    module_name = move_to_namespace(statement.tokens[2].text)
+    child = YARD::ModuleObject.new(module_name, object, statement.comments)
+    enter_namespace(child) { parse_block }
+  end
+end

data/lib/handlers/visibility_handler.rb

@@ -0,0 +1,7 @@
+class YARD::VisibilityHandler < YARD::CodeObjectHandler
+  handles /\A(protected|private|public)\Z/
+  
+  def process
+    self.current_visibility = statement.tokens.to_s.to_sym
+  end
+end

data/lib/handlers/yield_handler.rb

@@ -0,0 +1,31 @@
+class YARD::YieldHandler < YARD::CodeObjectHandler
+  handles 'yield'
+  
+  def process
+    tokens = statement.tokens.reject {|tk| [RubyToken::TkSPACE, RubyToken::TkLPAREN].include? tk.class }
+    from = tokens.each_with_index do |token, index|
+      break index if token.class == RubyToken::TkYIELD
+    end
+    if from.is_a? Fixnum
+      params = []
+      (from+1).step(tokens.size-1, 2) do |index|
+        # FIXME: This won't work if the yield has a method call or complex constant name (A::B) 
+        params << tokens[index].text
+        break unless tokens[index+1].is_a? RubyToken::TkCOMMA
+      end
+      
+      # Only add the tags if none were added at all
+      if object.tags("yieldparam").empty? && object.tags("yield").empty?
+        params.each do |param|
+          # TODO: We can technically introspect any constant to find out parameter types,
+          #       not just self.
+          # If parameter is self, we have a chance to get some extra information
+          if param == "self"
+            param = "[#{object.parent.path}] _self the object that yields the value (self)"
+          end
+          object.tags << YARD::TagLibrary.yieldparam_tag(param)
+        end
+      end
+    end
+  end
+end

data/lib/namespace.rb

@@ -0,0 +1,98 @@
+require 'singleton'
+require 'find'
+require 'yaml'
+require File.dirname(__FILE__) + '/code_object'
+require File.dirname(__FILE__) + '/source_parser'
+
+module YARD
+  class Namespace
+    DEFAULT_YARDOC_FILE = "_Yardoc"
+    
+    include Singleton
+    
+    class << self
+      ##
+      # Attempt to find a namespace and return it if it exists. Similar
+      # to the {YARD::Namsepace::at} method but creates the namespace
+      # as a module if it does not exist, and return it.
+      #
+      # @param [String] namespace the namespace to search for.
+      # @return [CodeObject] the namespace that was found or created.
+      def find_or_create_namespace(namespace)
+        return at(namespace) if at(namespace)
+        name = namespace.split("::").last
+        object = ModuleObject.new(name)
+        instance.namespace.update(namespace => object)
+        object
+      end
+      
+      def add_object(object)
+        instance.add_object(object)
+      end
+      
+      def at(name)
+        instance.at(name)
+      end
+      alias_method :[], :at
+      
+      def root
+        at('')
+      end
+      
+      def all
+        instance.namespace.keys
+      end
+      
+      def each_object
+        instance.namespace.each do |name, object|
+          yield(name, object)
+        end
+      end
+      
+      def load(file = DEFAULT_YARDOC_FILE, reload = false)
+        if File.exists?(file) && !reload
+          instance.namespace.replace(Marshal.load(IO.read(file)))
+        else
+          Find.find(".") do |path|
+            SourceParser.parse(path) if path =~ /\.rb$/
+          end
+        end
+        save
+      end
+      
+      def save(file = DEFAULT_YARDOC_FILE)
+        File.open(file, "w") {|f| Marshal.dump(instance.namespace, f) }
+      end
+      
+      def find_from_path(object, name)
+        object = at(object) unless object.is_a? CodeObject
+        return object if name == 'self'
+        
+        while object
+          ["::", ""].each do |type|
+            obj = at(object.path + type + name)
+            return obj if obj
+          end
+          object = object.parent
+        end
+        nil
+      end
+    end
+    
+    attr_reader :namespace
+    
+    def initialize
+      @namespace = { '' => CodeObjectWithMethods.new('', :root) }
+    end
+    
+    def add_object(object)
+      return object if namespace[object.path] && object.docstring.nil?
+      namespace.update(object.path => object)
+      object
+    end
+    
+    def at(name)
+      namespace[name]
+    end
+  end
+end

data/lib/quick_doc.rb

@@ -0,0 +1,104 @@
+require File.dirname(__FILE__) + '/namespace'
+
+module YARD
+  class QuickDoc
+    def initialize(name)
+      Namespace.load
+      if name.nil?
+        puts "Method Listing:"
+        puts "---------------"
+        puts Namespace.all.select {|n| Namespace.at(n).is_a? MethodObject }.sort.join("\n") 
+        return 
+      end
+      
+      meth = Namespace.at(name)
+      if meth.nil? 
+        puts "No entry for #{name}"
+        return
+      end
+      
+      ns = meth.path
+      rvalue = meth.tag('return')
+      return_type = rvalue && rvalue.type ? rvalue.type : "undefined"
+      block = nil
+      unless meth.tags("yieldparam").empty?
+        block = " {|" + meth.tags("yieldparam").collect {|tag| tag.name }.join(", ") + "| ... }"
+      end
+      
+      puts "Documentation for #{ns}"
+      puts "==================#{'=' * ns.length}"
+      if meth.file
+        puts "File: '#{meth.file}' (on line #{meth.line})"
+      end
+      puts "Type: #{return_type}\t\tVisibility: #{meth.visibility}"
+      puts
+      if meth.tag('deprecated')
+        desc = meth.tag('deprecrated').text
+        puts
+        puts "!! This method is deprecated" + (desc ? ": #{desc}" : ".")
+        puts
+      end
+      if meth.docstring
+        puts word_wrap(meth.docstring, ns.length + 18)
+        puts 
+      end
+      unless meth.tags("param").empty? && meth.tags("raise").empty? && meth.tags("return").empty?
+        puts "Meta Tags:"
+        puts "----------"
+        meth.tags("param").each do |tag|
+          types = tag.types.empty? ? "" : "[#{tag.types.join(", ")}] "
+          puts "> Parameter: #{types}#{tag.name} => #{tag.text}"
+        end
+        meth.tags("raise").each do |tag|
+          puts "> Raises #{tag.name} exception#{tag.text ? ': ' + tag.text : ''}"
+        end
+        meth.tags("return").each do |tag|
+          puts "> Returns #{tag.types.empty? ? "" : "(as " + tag.types.join(", ") + ')'} #{tag.text}"
+        end
+        puts
+        unless meth.tags("yieldparam").empty?
+          puts "Yields:"
+          puts "-------"
+          meth.tags("yieldparam").each do |tag|
+            types = tag.types.empty? ? "" : "[#{tag.types.join(", ")}] "
+            puts "> Block parameter: #{types}#{tag.name} => #{tag.text}"
+            puts
+          end
+        end
+      end
+      if meth.source
+        puts "Definition:"
+        puts "-----------"
+        puts format_code(meth.source.sub("\n", "#{block}" + (return_type ? " # -> " + return_type : "") + "\n"))
+        puts    
+      end
+      unless meth.tags("see").empty?
+        puts "See Also:"
+        puts "---------"
+        meth.tags("see").each do |tag|
+          puts "\t- #{tag.text}"
+        end
+        puts
+      end
+    end
+    
+    protected
+      def word_wrap(text, length = 80)
+        text.gsub(/(.{0,#{length - 3}}\s)/, "\n" + '\1')
+      end
+
+      def format_code(text, indent_size = 2)
+        last_indent, tab = nil, 0
+        text.split(/\r?\n/).collect do |line|
+          indent = line[/^(\s*)/, 1].length
+          if last_indent && indent > last_indent
+            tab += indent_size
+          elsif last_indent && indent < last_indent
+            tab -= indent_size
+          end
+          last_indent = indent
+          (" " * tab) + line.sub(/^\s*/, '')
+        end.join("\n")
+      end
+  end
+end