yard 0.2.1 → 0.2.2

data/spec/handlers/examples/mixin_handler_001.rb.txt

@@ -0,0 +1,12 @@
+module A; end
+module B; module C; end end
+
+class X
+  include A
+  include B, B::C, NOTEXIST
+end
+
+module Y
+  include B::C, B if X == 2
+  include A
+end

data/spec/handlers/examples/module_handler_001.rb.txt

@@ -0,0 +1,16 @@
+module ModName
+  private
+
+  # Docstring
+  module OtherModName
+  end
+end
+
+module            StressTest; end
+
+module A; end
+
+module Q
+	module A::B
+	end
+end

data/spec/handlers/examples/visibility_handler_001.rb.txt

@@ -0,0 +1,20 @@
+class Testing
+  def pub; end
+  
+  private
+
+  def priv; end
+  def notpriv; end
+  def notpriv2; end
+  def notpriv?; end
+
+  protected
+
+  def prot; end
+
+  public
+
+  def pub2; end
+
+  public :notpriv, 'notpriv2', :notpriv?
+end

data/spec/handlers/examples/yield_handler_001.rb.txt

@@ -0,0 +1,55 @@
+class Testing
+  # Ignore yields outside methods
+  yield x, y, z 
+  
+  # Should document this
+  def mymethod
+    yield
+  end
+  
+  # Has yield and yieldparam documentation
+  # @yield [a, b] Blah
+  # @yieldparam a Blah
+  # @yieldparam b Blah
+  def mymethod2
+    yield(b, a) # Yield something else
+  end
+  
+  # Has yield documentation only
+  # @yield [a, b]
+  def mymethod3 
+    yield self # Should not be changed
+  end
+  
+  # Has yieldparam documentation only
+  # @yieldparam _self BLAH
+  def mymethod4
+    yield self
+  end
+  
+  # Some weird possibilities..
+  # Document it all.
+  
+  
+  def mymethod5
+    yield :a, b, self, File.read('file', 'w'), CONSTANT if x == 2
+  end
+  
+  def mymethod6
+    yield(b, a)
+  end
+  
+  def mymethod7
+    yield a
+    yield b
+  end
+  
+  def mymethod8
+    yield self
+  end
+  
+  def mymethod9
+    yield super
+  end
+end
+  

data/spec/handlers/exception_handler_spec.rb

@@ -0,0 +1,35 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::ExceptionHandler do
+  before { parse_file :exception_handler_001, __FILE__ }
+  
+  it "should not document an exception outside of a method" do
+    P('Testing').has_tag?(:raise).should == false
+  end
+  
+  it "should document a valid raise" do
+    P('Testing#mymethod').tag(:raise).types.should == ['ArgumentError']
+  end
+  
+  it "should only document non-dynamic raises" do
+    P('Testing#mymethod2').tag(:raise).should be_nil
+    P('Testing#mymethod6').tag(:raise).should be_nil
+    P('Testing#mymethod7').tag(:raise).should be_nil
+  end
+  
+  it "should treat ConstantName.new as a valid exception class" do
+    P('Testing#mymethod8').tag(:raise).types.should == ['ExceptionClass']
+  end
+  
+  it "should not document a method with an existing @raise tag" do
+    P('Testing#mymethod3').tag(:raise).types.should == ['A']
+  end
+
+  it "should only document the first raise message of a method (limitation of exception handler)" do
+    P('Testing#mymethod4').tag(:raise).types.should == ['A']
+  end
+  
+  it "should handle complex class names" do
+    P('Testing#mymethod5').tag(:raise).types.should == ['YARD::Handlers::UndocumentableError']
+  end
+end

data/spec/handlers/method_handler_spec.rb

@@ -0,0 +1,35 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::MethodHandler do
+  before do
+    log.enter_level(Logger::ERROR) do
+      parse_file :method_handler_001, __FILE__ 
+    end
+  end
+  
+  it "should add methods to parent's #meths list" do
+    P(:Foo).meths.should include(P("Foo#method1"))
+  end
+  
+  it "should parse/add class methods (self.method2)" do
+    P(:Foo).meths.should include(P("Foo::method2"))
+  end
+  
+  it "should parse/add class methods from other namespaces (String::hello)" do
+    P("String::hello").should_not be_nil
+  end
+  
+  it "should allow punctuation in method names ([], ?, =~, <<, etc.)" do
+    [:[], :[]=, :allowed?, :/, :=~, :==, :`, :|, :*, :&, :%, :'^', :-@, :+@, :'~@'].each do |name|
+      Registry.at("Foo##{name}").should_not be_nil
+    end
+  end
+  
+  it "should mark dynamic methods as such" do
+    P('Foo#dynamic').dynamic?.should == true
+  end
+  
+  it "should show that a method is explicitly defined (if it was originally defined implicitly by attribute)" do
+    P('Foo#method1').is_explicit?.should == true
+  end
+end

data/spec/handlers/mixin_handler_spec.rb

@@ -0,0 +1,30 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::MixinHandler do
+  before { parse_file :mixin_handler_001, __FILE__ }
+  
+  it "should handle includes from classes or modules" do
+    Registry.at(:X).mixins.should include(P(:A))
+    Registry.at(:Y).mixins.should include(P(:A))
+  end
+  
+  it "should handle includes for complex namespaces" do
+  end
+  
+  it "should handle includes for modules that don't yet exist" do
+    Registry.at(:X).mixins.should include(P(nil, :NOTEXIST))
+  end
+  
+  it "should set the type of non-existing modules to :module" do
+    P(:NOTEXIST).type.should == :module
+  end
+  
+  it "should handle includes with multiple parameters" do
+    Registry.at(:X)
+  end
+  
+  it "should handle complex include statements" do
+    P(:Y).mixins.should include(P('B::C'))
+    P(:Y).mixins.should include(P(:B))
+  end
+end

data/spec/handlers/module_handler_spec.rb

@@ -0,0 +1,25 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::ModuleHandler do
+  before do
+    Registry.clear 
+    parse_file :module_handler_001, __FILE__
+  end
+
+  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
+end

data/spec/handlers/spec_helper.rb

@@ -0,0 +1,21 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper")
+
+include Handlers
+
+def undoc_error(code)
+  mock = mock("parser")
+  mock.stub!(:namespace).and_return(Registry.root)
+  mock.stub!(:namespace=).and_return nil
+  mock.stub!(:owner).and_return(Registry.root)
+  mock.stub!(:owner=).and_return nil
+  mock.stub!(:scope).and_return(:instance)
+  mock.stub!(:scope=).and_return nil
+  mock.stub!(:visibility).and_return(:public)
+  mock.stub!(:visibility=).and_return nil
+  mock.stub!(:file).and_return('<STDIN>')
+  mock.stub!(:parse).and_return nil
+  mock.stub!(:load_order_errors).and_return false
+  
+  c = self.class.described_type.new(mock, Parser::StatementList.new(code).first)
+  lambda { c.process }.should raise_error(UndocumentableError)
+end

data/spec/handlers/visibility_handler_spec.rb

@@ -0,0 +1,24 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::VisibilityHandler do
+  before { 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 == :public
+    Registry['Testing#notpriv2'].visibility.should == :public
+    Registry['Testing#notpriv?'].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::YieldHandler do
+  before { 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_not 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/parser/examples/example1.rb.txt

@@ -0,0 +1,8 @@
+module Hello
+  class Hi
+	# Docstring
+    def me
+      "Value"
+    end
+  end
+end

data/spec/parser/examples/tag_handler_001.rb.txt

@@ -0,0 +1,8 @@
+class Foo
+
+  # @api public
+  # @return nil
+  def foo
+  end
+
+end

data/spec/parser/source_parser_spec.rb

@@ -0,0 +1,43 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+
+describe YARD::Parser::SourceParser do
+  before do 
+    Registry.clear
+  end
+  
+  it "should parse basic Ruby code" do
+    Parser::SourceParser.parse_string(<<-eof)
+      module Hello
+        class Hi
+          # Docstring
+          def me; "VALUE" end
+        end
+      end
+    eof
+    Registry.at(:Hello).should_not == nil
+    Registry.at("Hello::Hi#me").should_not == nil
+    Registry.at("Hello::Hi#me").docstring.should == "Docstring"
+  end
+  
+  it "should parse a basic Ruby file" do
+    parse_file :example1, __FILE__
+    Registry.at(:Hello).should_not == nil
+    Registry.at("Hello::Hi#me").should_not == nil
+    Registry.at("Hello::Hi#me").docstring.should == "Docstring"
+  end
+  
+  it "should start with public visibility" do
+    p = Parser::SourceParser.new
+    p.visibility.should == :public
+  end
+  
+  it "should start in instance scope" do
+    p = Parser::SourceParser.new
+    p.scope.should == :instance
+  end
+  
+  it "should start in root namespace" do
+    p = Parser::SourceParser.new
+    p.namespace.should == Registry.root
+  end
+end

data/spec/parser/tag_parsing_spec.rb

@@ -0,0 +1,18 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+
+describe YARD::Parser, "tag handling" do
+  before { parse_file :tag_handler_001, __FILE__ }
+  
+  it "should know the list of all available tags" do
+    P("Foo#foo").tags.should include(P("Foo#foo").tag(:api))
+  end
+  
+  it "should know the text of tags on a method" do
+    P("Foo#foo").tag(:api).text.should == "public"
+  end
+  
+  it "should return true when asked whether a tag exists" do
+    P("Foo#foo").has_tag?(:api).should == true
+  end
+  
+end

data/spec/parser/token_list_spec.rb

@@ -0,0 +1,35 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+
+include YARD::Parser
+include YARD::Parser::RubyToken
+
+describe YARD::Parser::TokenList, "#initialize / #push" do
+  it "should accept a tokenlist (via constructor or push)" do
+    lambda { TokenList.new(TokenList.new) }.should_not raise_error(ArgumentError)
+    TokenList.new.push(TokenList.new("x = 2")).size.should == 6
+  end
+  
+  it "accept a token (via constructor or push)" do
+    lambda { TokenList.new(Token.new(0, 0)) }.should_not raise_error(ArgumentError)
+    TokenList.new.push(Token.new(0, 0), Token.new(1, 1)).size.should == 2
+  end
+  
+  it "should accept a string and parse it as code (via constructor or push)" do
+    lambda { TokenList.new("x = 2") }.should_not raise_error(ArgumentError)
+    x = TokenList.new
+    x.push("x", "=", "2")
+    x.size.should == 6
+    x.to_s.should == "x\n=\n2\n"
+  end
+  
+  it "should not accept any other input" do
+    lambda { TokenList.new(:notcode) }.should raise_error(ArgumentError)
+  end
+  
+  it "should not interpolate string data" do
+    x = TokenList.new('x = "hello #{world}"')
+    x.size.should == 6
+    x[4].class.should == TkDSTRING
+    x.to_s.should == 'x = "hello #{world}"' + "\n"
+  end
+end