yard 0.2.2 → 0.2.3

data/lib/yard/tags/default_tag.rb

@@ -0,0 +1,12 @@
+module YARD
+  module Tags
+    class DefaultTag < Tag
+      attr_reader :defaults
+      
+      def initialize(tag_name, text, types = nil, name = nil, defaults = nil)
+        super(tag_name, text, types, name)
+        @defaults = defaults
+      end
+    end
+  end
+end

data/lib/yard/tags/library.rb

@@ -5,31 +5,42 @@ module YARD
     # a new meta tag, you can do it in one of two ways.
     #
     # == Method #1
-    # Write your own +tagname_tag+ method that takes the raw text as a parameter.
-    # Example:
-    #   def mytag_tag(text)
-    #     Tag.parse_tag("mytag", text)
-    #   end
-    #
-    # This will allow you to use @mytag TEXT to add meta data to classes through
-    # the docstring. {Tag} has a few convenience factory methods to create 
-    #
-    # == Method #2
-    # Use {Library::define_tag!} to define a new tag by passing the tag name
+    # Use {Library.define_tag} to define a new tag by passing the tag name
     # and the factory method to use when creating the tag. These definitions will
-    # be auto expanded into ruby code similar to what is shown in method #1. If you
-    # do not provide a factory method to use, it will default to {Tag::parse_tag}
+    # be auto expanded into ruby code similar to what is shown in method #2. If you
+    # do not provide a factory method to use, it will default to {DefaultFactory#parse_tag}
     # Example:
     #   define_tag :param, :with_types_and_name
     #   define_tag :author
     #
     # The first line will expand to the code:
-    #   def param_tag(text) Tag.parse_tag_with_types_and_name(text) end
+    #   def param_tag(text) tag_factory.parse_tag_with_types_and_name(text) end
     #
     # The second line will expand to:
-    #   def author_tag(text) Tag.parse_tag(text) end
+    #   def author_tag(text) tag_factory.parse_tag(text) end
+    # 
+    # Note that +tag_factory+ is the factory object used to parse tags. This value
+    # defaults to the {DefaultFactory} class and can be set by changing {Library.default_factory}.
     #
-    # @see Library::define_tag
+    # == Method #2
+    # Write your own +tagname_tag+ method that takes the raw text as a parameter.
+    # Example:
+    #   def mytag_tag(text)
+    #     # parse your tag contents here
+    #   end
+    #
+    # This will allow you to use @mytag TEXT to add meta data to classes through
+    # the docstring. You can use the {Library#factory} object to help parse standard
+    # tag syntax. 
+    # 
+    # == Adding/Changing the Tag Syntax
+    # If you have specialized tag parsing needs you can substitute the {#factory} 
+    # object with your own by setting {Library.default_factory= Library.default_factory}
+    # to a new class with its own parsing methods before running YARD. This is useful
+    # if you want to change the syntax of existing tags (@see, @since, etc.)
+    #
+    # @see DefaultFactory
+    # @see Library.define_tag
     class Library
       class << self
         attr_reader :labels
@@ -39,6 +50,19 @@ module YARD
           @default_factory ||= DefaultFactory.new
         end
         
+        # Replace the factory object responsible for parsing tags by setting
+        # this to an object (or class) that responds to +parse_TAGNAME+ methods
+        # where +TAGNAME+ is the name of the tag.
+        # 
+        # You should set this value before performing any source parsing with
+        # YARD, otherwise your factory class will not be used.
+        # 
+        # @example
+        #   YARD::Tags::Library.default_factory = MyFactory
+        # 
+        # @param [Class, Object] factory the factory that parses all tags
+        # 
+        # @see DefaultFactory
         def default_factory=(factory)
           @default_factory = factory.is_a?(Class) ? factory.new : factory
         end
@@ -54,16 +78,25 @@ module YARD
       
         ##
         # Convenience method to define a new tag using one of {Tag}'s factory methods, or the
-        # regular {Tag::parse_tag} factory method if none is supplied.
+        # regular {DefaultFactory#parse_tag} factory method if none is supplied.
         #
         # @param [#to_s] tag the tag name to create
-        # @param meth the {Tag} factory method to call when creating the tag
+        # @param [#to_s, Class<Tag>] meth the {Tag} factory method to call when 
+        #   creating the tag or the name of the class to directly create a tag for
         def define_tag(label, tag, meth = "")
-          class_eval <<-eof, __FILE__, __LINE__
-            def #{tag}_tag(text, raw_text)
-              send_to_factory(#{tag.inspect}, #{meth.inspect}, text, raw_text)
-            end
-          eof
+          if meth.is_a?(Class) && Tag > meth
+            class_eval <<-eof, __FILE__, __LINE__
+              def #{tag}_tag(text, raw_text) 
+                #{meth}.new(#{tag.inspect}, text, raw_text) 
+              end
+            eof
+          else
+            class_eval <<-eof, __FILE__, __LINE__
+              def #{tag}_tag(text, raw_text)
+                send_to_factory(#{tag.inspect}, #{meth.inspect}, text, raw_text)
+              end
+            eof
+          end
 
           @labels ||= SymbolHash.new(false)
           @labels.update(tag => label)
@@ -86,12 +119,16 @@ module YARD
       
       public
       
+      # A factory class to handle parsing of tags, defaults to {default_factory}
+      attr_accessor :factory
+      
       def initialize(factory = Library.default_factory)
-        @factory = factory
+        self.factory = factory
       end
       
       define_tag "Parameters",        :param,       :with_types_and_name
       define_tag "Yield Parameters",  :yieldparam,  :with_types_and_name
+      define_tag "Yield Returns",     :yieldreturn, :with_types
       define_tag "Yields",            :yield,       :with_types
       define_tag "Default Value",     :default,     :with_name
       define_tag "Returns",           :return,      :with_types
@@ -102,8 +139,10 @@ module YARD
       define_tag "Since",             :since
       define_tag "Version",           :version
       define_tag "API Visibility",    :api
-      define_tag "Todo Item",         :todo      
+      define_tag "Todo Item",         :todo,        :with_raw_title_and_text
       define_tag "Example",           :example,     :with_raw_title_and_text
+      define_tag "Options Hash",      :option,      :with_options
+      define_tag "Overloads",         :overload,    OverloadTag
     end
   end
-end
+end

data/lib/yard/tags/option_tag.rb

@@ -0,0 +1,12 @@
+module YARD
+  module Tags
+    class OptionTag < Tag
+      attr_accessor :pair
+      
+      def initialize(tag_name, name, pair)
+        super(tag_name, nil, nil, name)
+        @pair = pair
+      end
+    end
+  end
+end

data/lib/yard/tags/overload_tag.rb

@@ -0,0 +1,62 @@
+module YARD
+  module Tags
+    class OverloadTag < Tag
+      attr_reader :signature, :parameters, :docstring
+      
+      def initialize(tag_name, text, raw_text)
+        super(tag_name, nil)
+        parse_tag(raw_text)
+        parse_signature
+      end
+      
+      def tag(name) docstring.tag(name) end
+      def tags(name = nil) docstring.tags(name) end
+      def has_tag?(name) docstring.has_tag?(name) end
+        
+      def object=(value)
+        super(value)
+        docstring.object = value
+      end
+
+      def type
+        object.type
+      end
+
+      def name(prefix = false)
+        object.name(prefix)
+      end
+
+      def inspect
+        "#<yardoc overload #{path}>"
+      end
+      
+      def method_missing(sym, *args, &block)
+        object ? object.send(sym, *args, &block) : super
+      end
+        
+      private
+      
+      def parse_tag(raw_text)
+        @signature, text = raw_text.split(/\r?\n/, 2)
+        text ||= ""
+        @signature.strip!
+        numspaces = text[/\A(\s*)/, 1].length
+        text.gsub!(/^[ \t]{#{numspaces}}/, '').strip!
+        @docstring = Docstring.new(text, nil)
+      end
+      
+      def parse_signature
+        if signature =~ /^(?:def)?\s*(#{CodeObjects::METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
+          meth, args = $1, $2
+          meth.gsub!(/\s+/,'')
+          # FIXME refactor this code to not make use of the Handlers::Base class (tokval_list should be moved)
+          toks = YARD::Parser::Ruby::Legacy::TokenList.new(args)
+          args = YARD::Handlers::Ruby::Legacy::Base.new(nil, nil).send(:tokval_list, toks, :all)
+          args.map! {|a| k, v = *a.split('=', 2); [k.strip.to_sym, (v ? v.strip : nil)] } if args
+          @name = meth.to_sym
+          @parameters = args
+        end
+      end
+    end
+  end
+end

data/lib/yard/tags/ref_tag.rb

@@ -0,0 +1,7 @@
+module YARD
+  module Tags
+    module RefTag
+      attr_accessor :owner
+    end
+  end
+end

data/lib/yard/tags/ref_tag_list.rb

@@ -0,0 +1,27 @@
+module YARD
+  module Tags
+    class RefTagList
+      attr_accessor :owner, :tag_name, :name
+      
+      def initialize(tag_name, owner, name = nil)
+        @owner = CodeObjects::Proxy === owner ? owner : P(owner)
+        @tag_name = tag_name.to_s
+        @name = name
+      end
+      
+      def tags
+        if owner.is_a?(CodeObjects::Base)
+          o = owner.tags(tag_name)
+          o = o.select {|t| t.name.to_s == name.to_s } if name
+          o.each do |t|
+            t.extend(RefTag)
+            t.owner = owner
+          end
+          o
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/yard/tags/tag.rb

@@ -2,6 +2,7 @@ module YARD
   module Tags
     class Tag
       attr_reader :tag_name, :text, :types, :name
+      attr_accessor :object
 
       ##
       # Creates a new tag object with a tag name and text. Optionally, formally declared types

data/lib/yard/tags/tag_format_error.rb

@@ -0,0 +1,6 @@
+module YARD
+  module Tags
+    class TagFormatError < Exception
+    end
+  end
+end

data/spec/cli/yardoc_spec.rb

@@ -0,0 +1,43 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+class YARD::CLI::Yardoc; public :optparse end
+
+describe YARD::CLI::Yardoc do
+  before do
+    @yardoc = YARD::CLI::Yardoc.new
+    @yardoc.stub!(:generate).and_return(false)
+    Registry.instance.stub!(:load)
+  end
+  
+  it "should select a markup provider when --markup-provider or -mp is set" do
+    @yardoc.optparse("-M", "test")
+    @yardoc.options[:markup_provider].should == :test
+    @yardoc.optparse("--markup-provider", "test2")
+    @yardoc.options[:markup_provider].should == :test2
+  end
+  
+  it "should search for and use yardopts file specified by #options_file" do
+    IO.should_receive(:read).with("test").and_return("-o \n\nMYPATH\nFILE1 FILE2")
+    @yardoc.stub!(:support_rdoc_document_file!).and_return([])
+    @yardoc.options_file = "test"
+    @yardoc.run
+    @yardoc.options[:serializer].options[:basepath].should == :MYPATH
+    @yardoc.files.should == ["FILE1", "FILE2"]
+  end
+  
+  it "should allow opts specified in command line to override yardopts file" do
+    IO.should_receive(:read).with(".yardopts").and_return("-o NOTMYPATH")
+    @yardoc.stub!(:support_rdoc_document_file!).and_return([])
+    @yardoc.run("-o", "MYPATH", "FILE")
+    @yardoc.options[:serializer].options[:basepath].should == :MYPATH
+    @yardoc.files.should == ["FILE"]
+  end
+  
+  it "should load the RDoc .document file if found" do
+    IO.should_receive(:read).with(".yardopts").and_return("-o NOTMYPATH")
+    @yardoc.stub!(:support_rdoc_document_file!).and_return(["FILE2", "FILE3"])
+    @yardoc.run("-o", "MYPATH", "FILE1")
+    @yardoc.options[:serializer].options[:basepath].should == :MYPATH
+    @yardoc.files.should == ["FILE1", "FILE2", "FILE3"]
+  end
+end

data/spec/code_objects/base_spec.rb

@@ -5,7 +5,7 @@ describe YARD::CodeObjects::Base do
   
   it "should return a unique instance of any registered object" do
     obj = ClassObject.new(:root, :Me)
-    obj2 = ModuleObject.new(:root, :Me)
+    obj2 = ClassObject.new(:root, :Me)
     obj.object_id.should == obj2.object_id
     
     obj3 = ModuleObject.new(obj, :Too)
@@ -15,6 +15,13 @@ describe YARD::CodeObjects::Base do
     obj5 = CodeObjects::Base.new(obj3, :hello)
     obj4.object_id.should_not == obj5.object_id
   end
+
+  it "should create a new object if cached object is not of the same class" do
+    ConstantObject.new(:root, "MYMODULE").should be_instance_of(ConstantObject)
+    ModuleObject.new(:root, "MYMODULE").should be_instance_of(ModuleObject)
+    ClassObject.new(:root, "MYMODULE").should be_instance_of(ClassObject)
+    YARD::Registry.at("MYMODULE").should be_instance_of(ClassObject)
+  end
   
   it "should recall the block if #new is called on an existing object" do
     o1 = ClassObject.new(:root, :Me) do |o|
@@ -30,50 +37,12 @@ describe YARD::CodeObjects::Base do
     o2.docstring.should == "NOT_DOCSTRING"
   end
   
-  it "should handle empty docstrings with #short_docstring" do
-    o1 = ClassObject.new(nil, :Me) 
-    o1.short_docstring.should == ""
-  end
-  
-  it "should return the first sentence with #short_docstring" do
-    o = ClassObject.new(nil, :Me) 
-    o.docstring = "DOCSTRING. Another sentence"
-    o.short_docstring.should == "DOCSTRING."
+  it "should convert string into Docstring when #docstring= is set" do
+    o = ClassObject.new(:root, :Me) 
+    o.docstring = "DOCSTRING"
+    o.docstring.should be_instance_of(Docstring)
   end
 
-  it "should return the first paragraph with #short_docstring" do
-    o = ClassObject.new(nil, :Me)
-    o.docstring = "DOCSTRING, and other stuff\n\nAnother sentence."
-    o.short_docstring.should == "DOCSTRING, and other stuff."
-  end
-  
-  it "should return proper short_docstring when docstring is changed" do
-    o = ClassObject.new(:root, :Me)
-    o.docstring = "DOCSTRING, and other stuff\n\nAnother sentence."
-    o.short_docstring.should == "DOCSTRING, and other stuff."
-    o.docstring = "DOCSTRING."
-    o.short_docstring.should == "DOCSTRING."
-  end
-  
-  it "should not double the ending period in short_docstring" do
-    o = ClassObject.new(nil, :Me)
-    o.docstring = "Returns a list of tags specified by +name+ or all tags if +name+ is not specified.\n\nTest"
-    o.short_docstring.should == "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
-    
-    Parser::SourceParser.parse_string <<-eof
-      ##
-      # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
-      #
-      # @param name the tag name to return data for, or nil for all tags
-      # @return [Array<Tags::Tag>] the list of tags by the specified tag name
-      def tags(name = nil)
-        return @tags if name.nil?
-        @tags.select {|tag| tag.tag_name.to_s == name.to_s }
-      end
-    eof
-    P('#tags').short_docstring.should == "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
-  end
-  
   it "should allow complex name and convert that to namespace" do
     obj = CodeObjects::Base.new(nil, "A::B")
     obj.namespace.path.should == "A"
@@ -97,7 +66,6 @@ describe YARD::CodeObjects::Base do
     obj.namespace.should == Registry.root
   end
   
-  
   it "should not allow any other types as namespace" do
     lambda { CodeObjects::Base.new("ROOT!", :Me) }.should raise_error(ArgumentError)
   end
@@ -137,30 +105,6 @@ describe YARD::CodeObjects::Base do
     obj.children.should include(obj2)
   end
   
-  it "should parse comments into tags" do
-    obj = CodeObjects::Base.new(nil, :Object)
-    comments = <<-eof
-      @param name Hello world
-        how are you?
-      @param name2 
-        this is a new line
-      @param name3 and this
-        is a new paragraph:
-
-        right here.
-    eof
-    obj.send(:parse_comments, comments)
-    obj.tags("param").each do |tag|
-      if tag.name == "name"
-        tag.text.should == "Hello world how are you?"
-      elsif tag.name == "name2"
-        tag.text.should == "this is a new line"
-      elsif tag.name == "name3"
-        tag.text.should == "and this is a new paragraph:\n\nright here."
-      end
-    end
-  end
-  
   it "should properly re-indent source starting from 0 indentation" do
     obj = CodeObjects::Base.new(nil, :test)
     obj.source = <<-eof
@@ -216,4 +160,48 @@ describe YARD::CodeObjects::Base do
     Parser::SourceParser.parse_string "def x; 2 end"
     Registry.at('#x').source.should == "def x; 2 end"
   end
+  
+  it "should set file and line information" do
+    Parser::SourceParser.parse_string <<-eof
+      class X; end
+    eof
+    Registry.at(:X).file.should == '(stdin)'
+    Registry.at(:X).line.should == 1
+  end
+  
+  it "should maintain all file associations when objects are defined multiple times in one file" do
+    Parser::SourceParser.parse_string <<-eof
+      class X; end
+      class X; end
+      class X; end
+    eof
+    
+    Registry.at(:X).file.should == '(stdin)'
+    Registry.at(:X).line.should == 1
+    Registry.at(:X).files.should == [['(stdin)', 1], ['(stdin)', 2], ['(stdin)', 3]]
+  end
+
+  it "should maintain all file associations when objects are defined multiple times in multiple files" do
+    3.times do |i|
+      IO.stub!(:read).and_return("class X; end")
+      Parser::SourceParser.new.parse("file#{i+1}.rb")
+    end
+    
+    Registry.at(:X).file.should == 'file1.rb'
+    Registry.at(:X).line.should == 1
+    Registry.at(:X).files.should == [['file1.rb', 1], ['file2.rb', 1], ['file3.rb', 1]]
+  end
+
+  it "should prioritize the definition with a docstring when returning #file" do
+    Parser::SourceParser.parse_string <<-eof
+      class X; end
+      class X; end
+      # docstring
+      class X; end
+    eof
+    
+    Registry.at(:X).file.should == '(stdin)'
+    Registry.at(:X).line.should == 4
+    Registry.at(:X).files.should == [['(stdin)', 4], ['(stdin)', 1], ['(stdin)', 2]]
+  end
 end