yard 0.2.1 → 0.2.2

data/spec/code_objects/proxy_spec.rb

@@ -0,0 +1,80 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::CodeObjects::Proxy do
+  before { Registry.clear }
+  
+  it "should return the object if it's in the Registry" do
+    pathobj = ModuleObject.new(:root, :YARD)
+    proxyobj = P(:root, :YARD)
+    proxyobj.type.should == :module
+    Proxy.should_not === proxyobj
+  end
+  
+  it "should handle complex string namespaces" do
+    ModuleObject.new(:root, :A)
+    pathobj = ModuleObject.new(P(nil, :A), :B)
+    P(:root, "A::B").should be_instance_of(ModuleObject)
+  end
+  
+  it "should not return true to Proxy === obj if obj is a Proxy class holding a resolved object" do
+    Proxy.should === P(:root, 'a')
+    Proxy.should_not === P(:root)
+    MethodObject.new(:root, 'a')
+    Proxy.should_not === P(:root, 'a')
+    x = Proxy.new(:root, 'a')
+    Proxy.should_not === x
+  end
+  
+  it "should return the object if it's an included Module" do
+    yardobj = ModuleObject.new(:root, :YARD)
+    pathobj = ClassObject.new(:root, :TestClass)
+    pathobj.mixins << yardobj
+    P(P(nil, :TestClass), :YARD).should be_instance_of(ModuleObject)
+  end
+  
+  it "should respond_to respond_to?" do
+    obj = ClassObject.new(:root, :Object)
+    yardobj = ModuleObject.new(:root, :YARD)
+    P(:YARD).respond_to?(:children).should == true
+    P(:NOTYARD).respond_to?(:children).should == false
+  end
+  
+  it "should make itself obvious that it's a proxy" do
+    pathobj = P(:root, :YARD)
+    pathobj.class.should == Proxy
+    (Proxy === pathobj).should == true
+  end    
+
+  it "should pretend it's the object's type if it can resolve" do
+    pathobj = ModuleObject.new(:root, :YARD)
+    proxyobj = P(:root, :YARD)
+    proxyobj.should be_instance_of(ModuleObject)
+  end
+  
+  it "should handle instance method names" do
+    obj = P(nil, '#test')
+    obj.name.should == :test
+    obj.path.should == "#test"
+    obj.namespace.should == Registry.root
+  end
+  
+  it "should handle instance method names under a namespace" do
+    pathobj = ModuleObject.new(:root, :YARD)
+    obj = P(pathobj, "A::B#test")
+    obj.name.should == :test
+    obj.path.should == "A::B#test"
+  end
+  
+  it "should allow type to be changed" do
+    obj = P("InvalidClass")
+    obj.type.should == :proxy
+    Proxy.should === obj
+    obj.type = :class
+    obj.type.should == :class
+  end
+  
+  it "should retain a type change between Proxy objects" do
+    P("InvalidClass").type = :class
+    P("InvalidClass").type.should == :class
+  end
+end

data/spec/code_objects/spec_helper.rb

@@ -0,0 +1,3 @@
+require File.join(File.dirname(__FILE__), "..", "spec_helper")
+
+include CodeObjects

data/spec/core_ext/file_spec.rb

@@ -0,0 +1,20 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe File, ".relative_path" do
+  it "should return the relative path between two files" do
+    File.relative_path('a/b/c/d.html', 'a/b/d/q.html').should == '../d/q.html'
+  end
+  
+  it "should return the relative path between two directories" do
+    File.relative_path('a/b/c/d/', 'a/b/d/').should == '../d'
+  end
+  
+  it "should return only the to file if from file is in the same directory as the to file" do
+    File.relative_path('a/b/c/d', 'a/b/c/e').should == 'e'
+  end
+  
+  it "should handle non-normalized paths" do
+    File.relative_path('Hello/./I/Am/Fred', 'Hello/Fred').should == '../../Fred'
+    File.relative_path('A//B/C', 'Q/X').should == '../../Q/X'
+  end
+end

data/spec/core_ext/string_spec.rb

@@ -0,0 +1,4 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+described_in_docs String, '#camelcase'
+described_in_docs String, '#underscore'

data/spec/core_ext/symbol_hash_spec.rb

@@ -0,0 +1,80 @@
+require File.join(File.dirname(__FILE__), '..', 'spec_helper')
+
+describe SymbolHash do
+  
+  it "should allow access to keys as String or Symbol" do
+    h = SymbolHash.new(false)
+    h['test'] = true
+    h[:test].should == true
+    h['test'].should == true
+  end
+    
+  it "should #delete by key as String or Symbol" do
+    h = SymbolHash.new
+    h.keys.length.should == 0
+
+    h['test'] = true
+    h.keys.length.should == 1
+
+    h.delete(:test)
+    h.keys.length.should == 0
+
+    h[:test] = true
+    h.keys.length.should == 1
+
+    h.delete('test')
+    h.keys.length.should == 0
+  end
+  
+  it "should return same #has_key? for key as String or Symbol" do
+    h = SymbolHash.new
+    h[:test] = 1
+    h.has_key?(:test).should == true
+    h.has_key?('test').should == true
+  end
+  
+  it "should symbolize value if it is a String (and only a string)" do
+    class Substring < String; end
+      
+    h = SymbolHash.new
+    h['test1'] = "hello"
+    h['test2'] = Substring.new("hello")
+    h['test1'].should == :hello
+    h['test2'].should == "hello"
+  end 
+  
+  it "should not symbolize value if SymbolHash.new(false) is created" do
+    h = SymbolHash.new(false)
+    h['test'] = "hello"
+    h[:test].should == "hello"
+  end
+  
+  it "should not symbolize value if it is not a String" do
+    h = SymbolHash.new
+    h['test'] = [1,2,3]
+    h['test'].should == [1,2,3]
+  end
+  
+  it "should support symbolization using #update or #merge" do
+    h = SymbolHash.new
+    h.update('test' => 'value')
+    h[:test].should == :value
+    h.merge('test' => 'value2')
+    h[:test].should == :value2
+  end
+  
+  it "should support #initializing of a hash" do
+    h = SymbolHash[:test => 1]
+    h[:test].should == 1
+    h[:somethingelse].should be_nil
+  end
+  
+  it "should support reverse merge syntax" do
+    opts = {}
+    opts = SymbolHash[
+      'default' => 1
+    ].update(opts)
+    opts.keys.should == [:default]
+    opts[:default].should == 1
+  end
+end

data/spec/generators/base_spec.rb

@@ -0,0 +1,64 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'stringio'
+
+include YARD::Generators
+
+describe YARD::Generators::Base, 'Section handling' do
+  before { Registry.clear }
+  
+  it "should allow a list of sections to be returned by sections_for" do
+    base = Generators::Base.new
+    base.stub!(:sections_for).and_return [:meth1, :meth2, :meth3]
+    base.should_receive(:meth1).and_return('a')
+    base.should_receive(:meth2).and_return('b')
+    base.should_receive(:meth3).and_return('c')
+    base.generate(Registry.root).should == 'abc'
+  end
+  
+  it "should allow a heirarchical list of sections to be returned by sections_for" do
+    base = Generators::Base.new
+    base.stub!(:sections_for).and_return [:meth1, [:meth2, :meth3]]
+    base.should_receive(:meth1).and_return('a')
+    base.should_not_receive(:meth2)
+    base.should_not_receive(:meth3)
+    base.generate(Registry.root).should == 'a'
+    base.current_object.should == Registry.root
+  end    
+  
+  it "should yield sub section lists to the parent section" do
+    class XYZ < Generators::Base
+      def sections_for(object) [:meth1, [:submeth1, :submeth2, [:submeth1]]] end
+      def meth1(object) object.name.to_s + yield(object) end
+      def submeth1(object) object.name.to_s end
+      def submeth2(object) object.name.to_s + yield(P(:YARD)) end
+    end
+
+    CodeObjects::Base.new(:root, :YARD)
+    XYZ.new.generate(Registry.root).should == "rootrootrootYARD"
+  end
+end
+
+describe YARD::Generators::Base, 'Rendering' do
+  it "should have a default template path" do
+    Generators::Base.template_paths.should == [YARD::TEMPLATE_ROOT]
+  end
+  
+  it "should find the right erb file to render given a template, format and name" do
+    base = Generators::Base.new
+    file = File.join(YARD::TEMPLATE_ROOT, 'default', 'base', 'html', 'name.erb')
+    File.should_receive(:file?).with(file).and_return(true)
+    File.should_receive(:read).with(file).and_return("output")
+    base.stub!(:sections_for).and_return([:name])
+    base.generate(Registry.root).should == "output"
+  end
+    
+  it "should allow the user to add extra search paths to find a custom template" do
+    Generators::Base.register_template_path 'doc'
+    base = Generators::Base.new
+    file = File.join('doc', 'default', 'base', 'html', 'name.erb')
+    File.should_receive(:file?).with(file).and_return(true)
+    File.should_receive(:read).with(file).and_return("output")
+    base.stub!(:sections_for).and_return([:name])
+    base.generate(Registry.root).should == "output"
+  end
+end

data/spec/generators/helpers/base_helper_spec.rb

@@ -0,0 +1,15 @@
+describe YARD::Generators::Helpers::BaseHelper, "#linkify" do
+  include YARD::Generators::Helpers::BaseHelper
+
+  it "should pass off to #link_object if argument is an object" do
+    obj = CodeObjects::NamespaceObject.new(nil, :YARD)
+    should_receive(:link_object).with(obj)
+    linkify obj
+  end
+  
+  it "should pass off to #link_url if argument is recognized as a URL" do
+    url = "http://yard.soen.ca/"
+    should_receive(:link_url).with(url)
+    linkify url
+  end
+end

data/spec/generators/helpers/html_helper_spec.rb

@@ -0,0 +1,56 @@
+describe YARD::Generators::Helpers::HtmlHelper, "basic HTML methods" do
+  include YARD::Generators::Helpers::HtmlHelper
+  
+  it "should use #h to escape HTML" do
+    h('Usage: foo "bar" <baz>').should == "Usage: foo &quot;bar&quot; &lt;baz&gt;"
+  end
+end
+
+describe YARD::Generators::Helpers::HtmlHelper, "#link_object" do
+  include YARD::Generators::Helpers::HtmlHelper
+  
+  it "should return the object path if there's no serializer and no title" do
+    stub!(:serializer).and_return nil
+    link_object(CodeObjects::NamespaceObject.new(nil, :YARD)).should == "YARD"
+  end
+  
+  it "should return the title if there's a title but no serializer" do
+    stub!(:serializer).and_return nil
+    link_object(CodeObjects::NamespaceObject.new(nil, :YARD), 'title').should == "title"
+  end
+end
+
+describe YARD::Generators::Helpers::HtmlHelper, '#url_for' do
+  include YARD::Generators::Helpers::HtmlHelper
+  
+  before { Registry.clear }
+  
+  it "should return nil if serializer is nil" do
+    stub!(:serializer).and_return nil
+    stub!(:current_object).and_return Registry.root
+    url_for(P("Mod::Class#meth")).should be_nil
+  end
+  
+  it "should return nil if serializer does not implement #serialized_path" do
+    stub!(:serializer).and_return Serializers::Base.new
+    stub!(:current_object).and_return Registry.root
+    url_for(P("Mod::Class#meth")).should be_nil
+  end
+  
+  it "should link to a path/file for a namespace object" do
+    stub!(:serializer).and_return Serializers::FileSystemSerializer.new
+    stub!(:current_object).and_return Registry.root
+    
+    yard = CodeObjects::ModuleObject.new(:root, :YARD)
+    url_for(yard).should == 'YARD.html'
+  end
+  
+  it "should link to the object's namespace path/file and use the object as the anchor" do
+    stub!(:serializer).and_return Serializers::FileSystemSerializer.new
+    stub!(:current_object).and_return Registry.root
+    
+    yard = CodeObjects::ModuleObject.new(:root, :YARD)
+    meth = CodeObjects::MethodObject.new(yard, :meth)
+    url_for(meth).should == 'YARD.html#meth-instance_method'
+  end
+end

data/spec/generators/quick_doc_generator_spec.rb

@@ -0,0 +1,13 @@
+describe YARD::Generators::QuickDocGenerator do
+  before { Registry.clear }
+  
+  it "should call all sections" do
+    Parser::SourceParser.parse_string(<<-eof)
+      class A
+        # Docstring
+        def method1; end
+      end
+    eof
+    g = Generators::QuickDocGenerator.new
+  end
+end

data/spec/handlers/alias_handler_spec.rb

@@ -0,0 +1,50 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::AliasHandler do
+  before do
+    Registry.clear 
+    parse_file :alias_handler_001, __FILE__
+  end
+
+  it "should throw alias into namespace object list" do
+    P(:A).aliases[P("A#b")].should == :a
+  end
+  
+  it "should handle the Ruby 'alias' keyword syntax" do
+    ['A#c', 'A#d?', 'A#[]', 'A#[]=', 'A#@-', 'A#%', 'A#*'].each do |a|
+      P(a).should be_instance_of(CodeObjects::MethodObject)
+    end
+  end
+  
+  it "should create a new method object for the alias" do
+    P("A#b").should be_instance_of(CodeObjects::MethodObject)
+  end
+  
+  it "should pull the method into the current class if it's from another one" do
+    P(:B).aliases[P("B#q")].should == :x
+    P(:B).aliases[P("B#r?")].should == :x
+  end
+  
+  it "should gracefully fail to pull a method in if the original method cannot be found" do
+    P(:B).aliases[P("B#s")].should == :to_s
+  end
+  
+  it "should allow complex Ruby expressions after the alias parameters" do
+    P(:B).aliases[P("B#t")].should == :inspect
+  end
+  
+  it "should show up in #is_alias? for method" do
+    P("B#t").is_alias?.should == true 
+    P('B#r?').is_alias?.should == true
+  end
+  
+  it "should raise an UndocumentableError if only one parameter is passed" do
+    undoc_error "alias_method :q"
+  end
+  
+  it "should raise an UndocumentableError if the parameter is not a Symbol or String" do
+    undoc_error "alias_method CONST, Something"
+    undoc_error "alias_method variable, ClassName"
+    undoc_error "alias_method variable, other_variable"
+  end
+end

data/spec/handlers/attribute_handler_spec.rb

@@ -0,0 +1,78 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe YARD::Handlers::AttributeHandler do
+  before { parse_file :attribute_handler_001, __FILE__ }
+  
+  def read_write(namespace, name, read, write, scope = :instance)
+    rname, wname = namespace.to_s+"#"+name.to_s, namespace.to_s+"#"+name.to_s+"="
+    if read
+      Registry.at(rname).should be_instance_of(CodeObjects::MethodObject) 
+    else
+      Registry.at(rname).should == nil
+    end
+    
+    if write
+      Registry.at(wname).should be_kind_of(CodeObjects::MethodObject) 
+    else
+      Registry.at(wname).should == nil
+    end     
+    
+    attrs = Registry.at(namespace).attributes[scope][name]
+    attrs[:read].should == (read ? Registry.at(rname) : nil)
+    attrs[:write].should == (write ? Registry.at(wname) : nil)
+  end
+  
+  it "should parse attributes inside modules too" do
+    Registry.at("A#x=").should_not == nil
+  end
+  
+  it "should parse 'attr'" do
+    read_write(:B, :a, true, true)
+    read_write(:B, :a2, true, false)
+    read_write(:B, "a3", true, false)
+  end
+  
+  it "should parse 'attr_reader'" do
+    read_write(:B, :b, true, false)
+  end
+  
+  it "should parse 'attr_writer'" do
+    read_write(:B, :e, false, true)
+  end
+  
+  it "should parse 'attr_accessor'" do
+    read_write(:B, :f, true, true)
+  end
+  
+  it "should parse a list of attributes" do
+    read_write(:B, :b, true, false)
+    read_write(:B, :c, true, false)
+    read_write(:B, :d, true, false)
+  end
+  
+  it "should have a default docstring if one is not supplied" do
+    Registry.at("B#f=").docstring.should_not be_empty
+  end
+  
+  it "should set the correct docstring if one is supplied" do
+    Registry.at("B#b").docstring.should == "Docstring"
+    Registry.at("B#c").docstring.should == "Docstring"
+    Registry.at("B#d").docstring.should == "Docstring"
+  end
+  
+  it "should be able to differentiate between class and instance attributes" do
+    P('B').class_attributes[:z][:read].scope.should == :class
+    P('B').instance_attributes[:z][:read].scope.should == :instance
+  end
+  
+  it "should respond true in method's #is_attribute?" do
+    P('B#a').is_attribute?.should == true
+    P('B#a=').is_attribute?.should == true
+  end
+  
+  it "should not return true for #is_explicit? in created methods" do
+    Registry.all(:method).each do |meth|
+      meth.is_explicit?.should == false
+    end
+  end
+end