deg-yard 0.8.7.1

data/spec/handlers/mixin_handler_spec.rb

@@ -0,0 +1,55 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}MixinHandler" do
+  before(:all) { parse_file :mixin_handler_001, __FILE__ }
+
+  it "should handle includes from classes or modules" do
+    Registry.at(:X).instance_mixins.should include(P(:A))
+    Registry.at(:Y).instance_mixins.should include(P(:A))
+  end
+
+  it "should handle includes in class << self" do
+    Registry.at(:Y).class_mixins.should include(P(:A))
+  end
+
+  it "should handle includes for modules that don't yet exist" do
+    Registry.at(:X).instance_mixins.should include(P(nil, :NOTEXIST))
+  end
+
+  it "should set the type of non-existing modules to :module" do
+    o = Registry.at(:X).instance_mixins.find {|o| o.name == :NOTEXIST }
+    o.type.should == :module
+  end
+
+  it "should handle includes with multiple parameters" do
+    Registry.at(:X).should_not be_nil
+  end
+
+  it "should handle complex include statements" do
+    P(:Y).instance_mixins.should include(P('B::C'))
+    P(:Y).instance_mixins.should include(P(:B))
+  end
+
+  it "should treat a mixed in Constant by taking its value as the real object name" do
+    P(:Y).instance_mixins.should include(Registry.at('B::D'))
+  end
+
+  it "should add includes in the correct order when include is given multiple arguments" do
+    P(:Z).instance_mixins.should == [P(:A), P(:B)]
+  end
+
+  it "should avoid including self for unresolved mixins of the same name" do
+    P("ABC::DEF::FOO").mixins.should == [P("ABC::FOO")]
+    P("ABC::DEF::BAR").mixins.should == [P("ABC::BAR")]
+  end
+
+  it "should raise undocumentable error if argument is variable" do
+    undoc_error "module X; include invalid; end"
+    Registry.at('X').mixins.should == []
+  end
+
+  it "should parse all other arguments before erroring out on undocumentable error" do
+    undoc_error "module X; include invalid, Y; end"
+    Registry.at('X').mixins.should == [P('Y')]
+  end
+end

data/spec/handlers/module_function_handler_spec.rb

@@ -0,0 +1,105 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}VisibilityHandler" do
+  after { Registry.clear }
+
+  def assert_module_function(namespace, name)
+    klass = Registry.at("#{namespace}.#{name}")
+    instance = Registry.at("#{namespace}##{name}")
+    klass.should_not be_nil
+    instance.should_not be_nil
+    klass.should be_module_function
+    instance.should_not be_module_function
+    klass.visibility.should == :public
+    instance.visibility.should == :private
+  end
+
+  it "should be able to create a module function with parameters" do
+    YARD.parse_string <<-eof
+      module Foo
+        def bar; end
+        def baz; end
+
+        module_function :bar, :baz
+      end
+    eof
+    assert_module_function('Foo', 'bar')
+    assert_module_function('Foo', 'baz')
+  end
+
+  it "should be able to set scope for duration of block without params" do
+    YARD.parse_string <<-eof
+      module Foo
+        def qux; end
+
+        module_function
+
+        def bar; end
+        def baz; end
+      end
+    eof
+    Registry.at('Foo.qux').should be_nil
+    assert_module_function('Foo', 'bar')
+    assert_module_function('Foo', 'baz')
+  end
+
+  # @bug gh-563
+  it "should copy tags to module function properly" do
+    YARD.parse_string <<-eof
+      module Foo
+        # @param [String] foo bar
+        # @option foo [String] bar (nil) baz
+        # @return [void]
+        def bar(foo); end
+        module_function :bar
+      end
+    eof
+    assert_module_function('Foo', 'bar')
+    o = Registry.at('Foo.bar')
+    o.tag(:param).types.should == ['String']
+    o.tag(:param).name.should == 'foo'
+    o.tag(:param).text.should == 'bar'
+    o.tag(:option).name.should == 'foo'
+    o.tag(:option).pair.types.should == ['String']
+    o.tag(:option).pair.defaults.should == ['nil']
+    o.tag(:option).pair.text.should == 'baz'
+    o.tag(:return).types.should == ['void']
+  end
+
+  it "should handle all method names in parameters" do
+    YARD.parse_string <<-eof
+      module Foo
+        def -(t); end
+        def ==(other); end
+        def a?; end
+        module_function :-, '==', :a?
+      end
+    eof
+    assert_module_function('Foo', '-')
+    assert_module_function('Foo', '==')
+    assert_module_function('Foo', 'a?')
+  end
+
+  it "should only accept strings and symbols" do
+    YARD.parse_string <<-eof
+      module Foo
+        module_function name
+        module_function *argument
+        module_function *(method_call)
+      end
+    eof
+    Registry.at('Foo#name').should be_nil
+    Registry.at('Foo#argument').should be_nil
+    Registry.at('Foo#method_call').should be_nil
+  end
+
+  it "should handle constants passed in as symbols" do
+    YARD.parse_string <<-eof
+      module Foo
+        def Foo; end
+        module_function :Foo
+      end
+    eof
+    assert_module_function('Foo', 'Foo')
+  end
+end

data/spec/handlers/module_handler_spec.rb

@@ -0,0 +1,34 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ModuleHandler" do
+  before(:all) { parse_file :module_handler_001, __FILE__ }
+
+  it "should parse a module block" do
+    Registry.at(:ModName).should_not == nil
+    Registry.at("ModName::OtherModName").should_not == nil
+  end
+
+  it "should attach docstring" do
+    Registry.at("ModName::OtherModName").docstring.should == "Docstring"
+  end
+
+  it "should handle any formatting" do
+    Registry.at(:StressTest).should_not == nil
+  end
+
+  it "should handle complex module names" do
+    Registry.at("A::B").should_not == nil
+  end
+
+  it "should handle modules in the form ::ModName" do
+    Registry.at("Kernel").should_not be_nil
+  end
+
+  it "should list mixins in proper order" do
+    Registry.at('D').mixins.should == [P(:C), P(:B), P(:A)]
+  end
+
+  it "should create proper module when constant is in namespace" do
+    Registry.at('Q::FOO::A').should_not be_nil
+  end
+end

data/spec/handlers/private_constant_handler_spec.rb

@@ -0,0 +1,24 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}PrivateConstantHandler" do
+  before(:all) { parse_file :private_constant_handler_001, __FILE__ }
+
+  it "should handle private_constant statement" do
+    Registry.at('A::Foo').visibility.should == :private
+    Registry.at('A::B').visibility.should == :private
+    Registry.at('A::C').visibility.should == :private
+  end
+
+  it "should make all other constants public" do
+    Registry.at('A::D').visibility.should == :public
+  end
+
+  it "should fail if parameter is not String, Symbol or Constant" do
+    undoc_error 'class Foo; private_constant x; end'
+    undoc_error 'class Foo; X = 1; private_constant X.new("hi"); end'
+  end unless LEGACY_PARSER
+
+  it "should fail if constant can't be recognized" do
+    undoc_error 'class Foo2; private_constant :X end'
+  end
+end

data/spec/handlers/processor_spec.rb

@@ -0,0 +1,34 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::Processor do
+  before do
+    @proc = Handlers::Processor.new(OpenStruct.new(:parser_type => :ruby))
+  end
+
+  it "should start with public visibility" do
+    @proc.visibility.should == :public
+  end
+
+  it "should start in instance scope" do
+    @proc.scope.should == :instance
+  end
+
+  it "should start in root namespace" do
+    @proc.namespace.should == Registry.root
+  end
+
+  it "should have a globals structure" do
+    @proc.globals.should be_a(OpenStruct)
+  end
+
+  it 'should ignore HandlerAborted exceptions (but print debug info)' do
+    class AbortHandlerProcessor < YARD::Handlers::Ruby::Base
+      process { abort! }
+    end
+    stmt = OpenStruct.new(:line => 1, :show => 'SOURCE')
+    @proc.stub!(:find_handlers).and_return([AbortHandlerProcessor])
+    log.should_receive(:debug).with(/AbortHandlerProcessor cancelled from/)
+    log.should_receive(:debug).with("\tin file '(stdin)':1:\n\nSOURCE\n")
+    @proc.process([stmt])
+  end
+end

data/spec/handlers/ruby/base_spec.rb

@@ -0,0 +1,94 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe YARD::Handlers::Ruby::Base, '#valid_handler?' do
+  include YARD::Parser::Ruby; YARD::Parser::Ruby::AstNode
+
+  before do
+    Handlers::Ruby::Base.stub!(:inherited)
+    @processor = Handlers::Processor.new(OpenStruct.new(:parser_type => :ruby))
+  end
+
+  after(:all) do
+    Handlers::Base.clear_subclasses
+  end
+
+  def valid(handler, stmt)
+    @processor.find_handlers(stmt).should include(handler)
+  end
+
+  def invalid(handler, stmt)
+    @processor.find_handlers(stmt).should_not include(handler)
+  end
+
+  it "should only handle Handlers inherited from Ruby::Base class" do
+    class IgnoredHandler < Handlers::Base
+      handles :list
+    end
+    class NotIgnoredHandler < Handlers::Ruby::Base
+      handles :list
+    end
+    Handlers::Base.stub!(:subclasses).and_return [IgnoredHandler, NotIgnoredHandler]
+    @processor.find_handlers(s()).should == [NotIgnoredHandler]
+  end
+
+  it "should handle string input (matches AstNode#source)" do
+    class StringHandler < Handlers::Ruby::Base
+      handles "x"
+    end
+    Handlers::Base.stub!(:subclasses).and_return [StringHandler]
+    ast = Parser::Ruby::RubyParser.parse("if x == 2 then true end").ast
+    valid StringHandler, ast[0][0][0]
+    invalid StringHandler, ast[0][1]
+  end
+
+  it "should handle symbol input (matches AstNode#type)" do
+    class SymbolHandler < Handlers::Ruby::Base
+      handles :myNodeType
+    end
+    Handlers::Base.stub!(:subclasses).and_return [SymbolHandler]
+    valid SymbolHandler, s(:myNodeType, s(1, 2, 3))
+    invalid SymbolHandler, s(:NOTmyNodeType, s(1, 2, 3))
+  end
+
+  it "should handle regex input (matches AstNode#source)" do
+    class RegexHandler < Handlers::Ruby::Base
+      handles %r{^if x ==}
+    end
+    Handlers::Base.stub!(:subclasses).and_return [RegexHandler]
+    ast = Parser::Ruby::RubyParser.parse("if x == 2 then true end").ast
+    valid RegexHandler, ast
+    invalid RegexHandler, ast[0][1]
+  end
+
+  it "should handle AstNode input (matches AST literally)" do
+    class ASTHandler < Handlers::Ruby::Base
+      handles s(:vcall, s(:ident, "hello_world"))
+    end
+    Handlers::Base.stub!(:subclasses).and_return [ASTHandler]
+    valid ASTHandler, s(:vcall, s(:ident, "hello_world"))
+    invalid ASTHandler, s(:vcall, s(:ident, "NOTHELLOWORLD"))
+  end
+
+  it "should handle #method_call(:methname) on a valid AST" do
+    class MethCallHandler < Handlers::Ruby::Base
+      handles method_call(:meth)
+    end
+    Handlers::Base.stub!(:subclasses).and_return [MethCallHandler]
+    ast = Parser::Ruby::RubyParser.parse(<<-"eof").ast
+      meth                   # 0
+      meth()                 # 1
+      meth(1,2,3)            # 2
+      meth 1,2,3             # 3
+      NotMeth.meth           # 4
+      NotMeth.meth { }       # 5
+      NotMeth.meth do end    # 6
+      NotMeth.meth 1, 2, 3   # 7
+      NotMeth.meth(1, 2, 3)  # 8
+      NotMeth                # 9
+    eof
+    (0..8).each do |i|
+      valid MethCallHandler, ast[i]
+    end
+    invalid MethCallHandler, ast[9]
+  end
+end if HAVE_RIPPER

data/spec/handlers/ruby/legacy/base_spec.rb

@@ -0,0 +1,82 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+include Parser::Ruby::Legacy
+
+describe YARD::Handlers::Ruby::Legacy::Base, "#handles and inheritance" do
+  before do
+    Handlers::Ruby::Legacy::Base.stub!(:inherited)
+    Handlers::Ruby::Legacy::MixinHandler.stub!(:inherited) # fixes a Ruby1.9 issue
+    @processor = Handlers::Processor.new(OpenStruct.new(:parser_type => :ruby18))
+  end
+
+  after(:all) do
+    Handlers::Base.clear_subclasses
+  end
+
+  def stmt(string)
+    Statement.new(TokenList.new(string))
+  end
+
+  it "should only handle Handlers inherited from Ruby::Legacy::Base class" do
+    class IgnoredHandler < Handlers::Base
+      handles "hello"
+    end
+    class NotIgnoredHandlerLegacy < Handlers::Ruby::Legacy::Base
+      handles "hello"
+    end
+    Handlers::Base.stub!(:subclasses).and_return [IgnoredHandler, NotIgnoredHandlerLegacy]
+    @processor.find_handlers(stmt("hello world")).should == [NotIgnoredHandlerLegacy]
+  end
+
+  it "should handle a string input" do
+    class TestStringHandler < Handlers::Ruby::Legacy::Base
+      handles "hello"
+    end
+
+    TestStringHandler.handles?(stmt("hello world")).should be_true
+    TestStringHandler.handles?(stmt("nothello world")).should be_false
+  end
+
+  it "should handle regex input" do
+    class TestRegexHandler < Handlers::Ruby::Legacy::Base
+      handles /^nothello$/
+    end
+
+    TestRegexHandler.handles?(stmt("nothello")).should be_true
+    TestRegexHandler.handles?(stmt("not hello hello")).should be_false
+  end
+
+  it "should handle token input" do
+    class TestTokenHandler < Handlers::Ruby::Legacy::Base
+      handles TkMODULE
+    end
+
+    TestTokenHandler.handles?(stmt("module")).should be_true
+    TestTokenHandler.handles?(stmt("if")).should be_false
+  end
+
+  it "should parse a do/end or { } block with #parse_block" do
+    class MyBlockHandler < Handlers::Ruby::Legacy::Base
+      handles /\AmyMethod\b/
+      def process
+        parse_block(:owner => "test")
+      end
+    end
+
+    class MyBlockInnerHandler < Handlers::Ruby::Legacy::Base
+      handles "inner"
+      def self.reset; @@reached = false end
+      def self.reached?; @@reached ||= false end
+      def process; @@reached = true end
+    end
+
+    Handlers::Base.stub!(:subclasses).and_return [MyBlockHandler, MyBlockInnerHandler]
+    Parser::SourceParser.parser_type = :ruby18
+    Parser::SourceParser.parse_string "myMethod do inner end"
+    MyBlockInnerHandler.should be_reached
+    MyBlockInnerHandler.reset
+    Parser::SourceParser.parse_string "myMethod { inner }"
+    MyBlockInnerHandler.should be_reached
+    Parser::SourceParser.parser_type = :ruby
+  end
+end

data/spec/handlers/spec_helper.rb

@@ -0,0 +1,33 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper")
+require 'stringio'
+
+include Handlers
+
+def undoc_error(code)
+  lambda { StubbedSourceParser.parse_string(code) }.should raise_error(Parser::UndocumentableError)
+end
+
+def with_parser(parser_type, &block)
+  tmp = StubbedSourceParser.parser_type
+  StubbedSourceParser.parser_type = parser_type
+  yield
+  StubbedSourceParser.parser_type = tmp
+end
+
+class StubbedProcessor < Processor
+  def process(statements)
+    statements.each_with_index do |stmt, index|
+      find_handlers(stmt).each do |handler|
+        handler.new(self, stmt).process
+      end
+    end
+  end
+end
+
+class StubbedSourceParser < Parser::SourceParser
+  StubbedSourceParser.parser_type = :ruby
+  def post_process
+    post = StubbedProcessor.new(self)
+    post.process(@parser.enumerator)
+  end
+end

data/spec/handlers/visibility_handler_spec.rb

@@ -0,0 +1,39 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}VisibilityHandler" do
+  before(:all) { parse_file :visibility_handler_001, __FILE__ }
+
+  it "should be able to set visibility to public" do
+    Registry.at("Testing#pub").visibility.should == :public
+    Registry.at("Testing#pub2").visibility.should == :public
+  end
+
+  it "should be able to set visibility to private" do
+    Registry.at("Testing#priv").visibility.should == :private
+  end
+
+  it "should be able to set visibility to protected" do
+    Registry.at("Testing#prot").visibility.should == :protected
+  end
+
+  it "should support parameters and only set visibility on those methods" do
+    Registry['Testing#notpriv'].visibility.should == :protected
+    Registry['Testing#notpriv2'].visibility.should == :protected
+    Registry['Testing#notpriv?'].visibility.should == :protected
+  end
+
+  it "should only accept strings and symbols" do
+    Registry.at('Testing#name').should be_nil
+    Registry.at('Testing#argument').should be_nil
+    Registry.at('Testing#method_call').should be_nil
+  end
+
+  it "should handle constants passed in as symbols" do
+    Registry.at('Testing#Foo').visibility.should == :private
+  end
+
+  it 'should not register classes with visibility' do
+    Registry.at('Testing::Bar').visibility.should == :public
+    Registry.at('Testing::Baz').visibility.should == :public
+  end
+end

data/spec/handlers/yield_handler_spec.rb

@@ -0,0 +1,51 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}YieldHandler" do
+  before(:all) { parse_file :yield_handler_001, __FILE__ }
+
+  it "should only parse yield blocks in methods" do
+    P(:Testing).tag(:yield).should be_nil
+    P(:Testing).tag(:yieldparam).should be_nil
+  end
+
+  it "should handle an empty yield statement" do
+    P('Testing#mymethod').tag(:yield).should be_nil
+    P('Testing#mymethod').tag(:yieldparam).should be_nil
+  end
+
+  it "should not document a yield statement in a method with either @yield or @yieldparam" do
+    P('Testing#mymethod2').tag(:yield).types.should == ['a', 'b']
+    P('Testing#mymethod2').tag(:yield).text.should == "Blah"
+    P('Testing#mymethod2').tags(:yieldparam).size.should == 2
+
+    P('Testing#mymethod3').tag(:yield).types.should == ['a', 'b']
+    P('Testing#mymethod3').tags(:yieldparam).size.should == 0
+
+    P('Testing#mymethod4').tag(:yieldparam).name.should == '_self'
+    P('Testing#mymethod4').tag(:yieldparam).text.should == 'BLAH'
+  end
+
+  it "should handle any arbitrary yield statement" do
+    P('Testing#mymethod5').tag(:yield).types.should == [':a', 'b', '_self', 'File.read(\'file\', \'w\')', 'CONSTANT']
+  end
+
+  it "should handle parentheses" do
+    P('Testing#mymethod6').tag(:yield).types.should == ['b', 'a']
+  end
+
+  it "should only document the first yield statement in a method (limitation of yield handler)" do
+    P('Testing#mymethod7').tag(:yield).types.should == ['a']
+  end
+
+  it "should handle `self` keyword and list object type as yieldparam for _self" do
+    P('Testing#mymethod8').tag(:yield).types.should == ['_self']
+    P('Testing#mymethod8').tag(:yieldparam).types.should == ['Testing']
+    P('Testing#mymethod8').tag(:yieldparam).text.should == "the object that the method was called on"
+  end
+
+  it "should handle `super` keyword and document it under _super" do
+    P('Testing#mymethod9').tag(:yield).types.should == ['_super']
+    P('Testing#mymethod9').tag(:yieldparam).types.should be_nil
+    P('Testing#mymethod9').tag(:yieldparam).text.should == "the result of the method from the superclass"
+  end
+end

data/spec/i18n/locale_spec.rb

@@ -0,0 +1,68 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe YARD::I18n::Locale do
+  def locale(name)
+    YARD::I18n::Locale.new(name)
+  end
+
+  before do
+    @locale = locale("fr")
+  end
+
+  describe "#name" do
+    it "should return name" do
+      locale("fr").name.should == "fr"
+    end
+  end
+
+  describe "#load" do
+    it "should return false for nonexistent PO" do
+      File.should_receive(:exist?).with('foo/fr.po').and_return(false)
+      @locale.load('foo').should == false
+    end
+
+    have_gettext_gem = true
+    begin
+      require "gettext/tools/poparser"
+    rescue LoadError
+      have_gettext_gem = false
+    end
+    it "should return true for existent PO", :if => have_gettext_gem do
+      data = <<-eop
+msgid ""
+msgstr ""
+"Language: fr\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+msgid "Hello"
+msgstr "Bonjour"
+eop
+      parser = GetText::PoParser.new
+      File.should_receive(:exist?).with('foo/fr.po').and_return(true)
+      GetText::PoParser.should_receive(:new).and_return(parser)
+      parser.should_receive(:parse_file) do |file, hash|
+        file.should == 'foo/fr.po'
+        parser.parse(data, hash)
+      end
+      @locale.load('foo').should == true
+      @locale.translate('Hello').should == "Bonjour"
+    end
+  end
+
+  describe "#translate" do
+    before do
+      messages = @locale.instance_variable_get(:@messages)
+      messages["Hello"] = "Bonjour"
+    end
+
+    it "should return translated string for existent string" do
+      @locale.translate("Hello") == "Bonjour"
+    end
+
+    it "should return original string for nonexistent string" do
+      @locale.translate("nonexistent") == "nonexistent"
+    end
+  end
+end

data/spec/i18n/message_spec.rb

@@ -0,0 +1,52 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe YARD::I18n::Message do
+  def message(id)
+    YARD::I18n::Message.new(id)
+  end
+
+  before do
+    @message = message("Hello World!")
+  end
+
+  describe "#id" do
+    it "should return ID" do
+      message("Hello World!").id.should == "Hello World!"
+    end
+  end
+
+  describe "#add_location" do
+    it "should add some locations" do
+      @message.add_location("hello.rb", 10)
+      @message.add_location("message.rb", 5)
+      @message.locations.should == Set.new([["hello.rb", 10], ["message.rb", 5]])
+    end
+  end
+
+  describe "#add_comment" do
+    it "should add some comments" do
+      @message.add_comment("YARD.title")
+      @message.add_comment("Hello#message")
+      @message.comments.should == Set.new(["YARD.title", "Hello#message"])
+    end
+  end
+
+  describe "#==" do
+    it "should return true for same value messages" do
+      locations = [["hello.rb", 10], ["message.rb", 5]]
+      comments = ["YARD.title", "Hello#message"]
+
+      other_message = message(@message.id)
+      locations.each do |path, line|
+        @message.add_location(path, line)
+        other_message.add_location(path, line)
+      end
+      comments.each do |comment|
+        @message.add_comment(comment)
+        other_message.add_comment(comment)
+      end
+
+      @message.should == other_message
+    end
+  end
+end