yard 0.2.1 → 0.2.2

data/spec/registry_spec.rb

@@ -0,0 +1,70 @@
+require File.join(File.dirname(__FILE__), "spec_helper")
+include CodeObjects
+
+describe YARD::Registry do
+  before { Registry.clear }
+  it "should have an empty path for root" do
+    Registry.root.path.should == ""
+  end
+  
+  it "should #resolve any existing namespace" do
+    o1 = ModuleObject.new(:root, :A)
+    o2 = ModuleObject.new(o1, :B)
+    o3 = ModuleObject.new(o2, :C)
+    Registry.resolve(o1, "B::C").should == o3
+    Registry.resolve(:root, "A::B::C")
+  end
+  
+  it "should resolve an object in the root namespace when prefixed with ::" do
+    o1 = ModuleObject.new(:root, :A)
+    o2 = ModuleObject.new(o1, :B)
+    o3 = ModuleObject.new(o2, :C)
+    Registry.resolve(o3, "::A").should == o1
+    
+    Registry.resolve(o3, "::String", true).should == P(:String)
+  end
+  
+  it "should resolve instance methods with # prefix" do
+    o1 = ModuleObject.new(:root, :A)
+    o2 = ModuleObject.new(o1, :B)
+    o3 = ModuleObject.new(o2, :C)
+    o4 = MethodObject.new(o3, :methname)
+    Registry.resolve(o1, "B::C#methname").should == o4
+    Registry.resolve(o2, "C#methname").should == o4
+    Registry.resolve(o3, "#methname").should == o4
+  end
+  
+  it "should resolve instance methods in the root without # prefix" do
+    o = MethodObject.new(:root, :methname)
+    Registry.resolve(:root, 'methname').should == o
+  end
+  
+  it "should allow symbols as object type in #all" do
+    ModuleObject.new(:root, :A)
+    o1 = ClassObject.new(:root, :B)
+    o2 = MethodObject.new(:root, :testing)
+    r = Registry.all(:method, :class)
+    r.should include(o1, o2)
+  end
+  
+  it "should allow code object classes in #all" do
+    o1 = ModuleObject.new(:root, :A)
+    o2 = ClassObject.new(:root, :B)
+    MethodObject.new(:root, :testing)
+    r = Registry.all(CodeObjects::NamespaceObject)
+    r.should include(o1, o2)
+  end
+  
+  it "should allow #all to omit list" do
+    o1 = ModuleObject.new(:root, :A)
+    o2 = ClassObject.new(:root, :B)
+    r = Registry.all
+    r.should include(o1, o2)
+  end
+  
+  it "should respond to #paths" do
+    o1 = ModuleObject.new(:root, :A)
+    o2 = ClassObject.new(:root, :B)
+    Registry.paths.should include('A', 'B')
+  end
+end

data/spec/serializers/file_system_serializer_spec.rb

@@ -0,0 +1,91 @@
+require File.join(File.dirname(__FILE__), "spec_helper")
+
+require 'stringio'
+
+describe YARD::Serializers::FileSystemSerializer do
+  before do
+    FileUtils.stub!(:mkdir_p)
+    File.stub!(:open)
+  end
+  
+  it "should default the base path to the 'doc/'" do
+    obj = Serializers::FileSystemSerializer.new
+    obj.basepath.should == 'doc'
+  end
+  
+  it "should default the file extension to .html" do
+    obj = Serializers::FileSystemSerializer.new
+    obj.extension.should == "html"
+  end
+  
+  it "should allow no extension to be used" do
+    obj = Serializers::FileSystemSerializer.new :extension => nil
+    obj.serialized_path(Registry.root).should == 'root'
+  end
+  
+  it "should serialize to the correct path" do
+    yard = CodeObjects::ClassObject.new(nil, :FooBar)
+    meth = CodeObjects::MethodObject.new(yard, :baz, :class)
+    meth2 = CodeObjects::MethodObject.new(yard, :baz)
+    
+    { 'foo/FooBar/baz_c.txt' => meth,
+      'foo/FooBar/baz_i.txt' => meth2,
+      'foo/FooBar.txt' => yard }.each do |path, obj|
+      io = StringIO.new
+      File.should_receive(:open).with(path, 'w').and_yield(io)
+      io.should_receive(:write).with("data")
+    
+      s = Serializers::FileSystemSerializer.new(:basepath => 'foo', :extension => 'txt')
+      s.serialize(obj, "data")
+    end
+  end
+  
+  it "should return serialized_path for a String" do
+    s = Serializers::FileSystemSerializer.new(:basepath => 'foo', :extension => 'txt')
+    s.serialized_path('test.txt').should == 'test.txt'
+  end
+  
+  it "should remove special chars from path" do
+    m = CodeObjects::MethodObject.new(nil, 'a')
+    s = Serializers::FileSystemSerializer.new
+    
+    { :/ => '_2F_i.html',
+      :gsub! => 'gsub_21_i.html', 
+      :ask? => 'ask_3F_i.html', 
+      :=== => '_3D_3D_3D_i.html', 
+      :+ => '_2B_i.html', 
+      :- => '-_i.html', 
+      :[]= => '_5B_5D_3D_i.html',
+      :<< => '_3C_3C_i.html',
+      :>= => '_3E_3D_i.html',
+      :` => '_60_i.html',
+      :& => '_26_i.html',
+      :* => '_2A_i.html',
+      :| => '_7C_i.html',
+      :/ => '_2F_i.html',
+      :=~ => '_3D_7E_i.html'
+    }.each do |meth, value|
+      m.stub!(:name).and_return(meth)
+      s.serialized_path(m).should == value
+    end
+  end
+  
+  it "should differentiate instance and class methods from serialized path" do
+    s = Serializers::FileSystemSerializer.new
+    m1 = CodeObjects::MethodObject.new(nil, 'meth')
+    m2 = CodeObjects::MethodObject.new(nil, 'meth', :class)
+    s.serialized_path(m1).should_not == s.serialized_path(m2)
+  end
+  
+  it "should guarantee the directory exists" do
+    o1 = CodeObjects::ClassObject.new(nil, :Really)
+    o2 = CodeObjects::ClassObject.new(o1, :Long)
+    o3 = CodeObjects::ClassObject.new(o2, :PathName)
+    obj = CodeObjects::MethodObject.new(o3, :foo)
+
+    FileUtils.should_receive(:mkdir_p).once.with('doc/Really/Long/PathName')
+    
+    s = Serializers::FileSystemSerializer.new
+    s.serialize(obj, "data")
+  end
+end

data/spec/serializers/spec_helper.rb

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

data/spec/spec_helper.rb

@@ -0,0 +1,77 @@
+require "rubygems"
+require "spec"
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
+
+def parse_file(file, thisfile = __FILE__)
+  Registry.clear
+  path = File.join(File.dirname(thisfile), 'examples', file.to_s + '.rb.txt')
+  p = YARD::Parser::SourceParser.new
+  p.parse(path)
+  p
+end
+
+def described_in_docs(klass, meth, file = nil)
+  YARD::Tags::Library.define_tag "RSpec Specification", :it, :with_raw_title_and_text
+
+  # Parse the file (could be multiple files)
+  if file
+    filename = File.join(YARD::ROOT, file)
+    YARD::Parser::SourceParser.new.parse(filename)
+  else
+    $".find_all {|p| p.include? klass.class_name.underscore }.each do |filename|
+      next unless File.exists? filename
+      YARD::Parser::SourceParser.new.parse(filename)
+    end
+  end
+  
+  # Get the object
+  objname = klass.name + (meth[0,1] == '#' ? meth : '::' + meth)
+  obj = Registry.at(objname)
+  raise "Cannot find object #{objname} described by spec." unless obj
+  raise "#{obj.path} has no @it tags to spec." unless obj.has_tag? :it
+  
+  # Run examples
+  describe(klass, meth) do
+    obj.tags(:it).each do |it|
+      path = File.relative_path(YARD::ROOT, obj.file)
+      it(it.name + " (from #{path}:#{obj.line})") do 
+        begin
+          eval(it.text)
+        rescue => e
+          e.set_backtrace(["#{path}:#{obj.line}:in @it tag specification"])
+          raise e
+        end
+      end
+    end
+  end
+end
+
+def docspec(objname = self.class.description, klass = self.class.described_type)
+  # Parse the file (could be multiple files)
+  $".find_all {|p| p.include? klass.class_name.underscore }.each do |filename|
+    filename = File.join(YARD::ROOT, filename)
+    next unless File.exists? filename
+    YARD::Parser::SourceParser.new.parse(filename)
+  end
+  
+  # Get the object
+  objname = klass.name + objname if objname =~ /^[^A-Z]/
+  obj = Registry.at(objname)
+  raise "Cannot find object #{objname} described by spec." unless obj
+  raise "#{obj.path} has no @example tags to spec." unless obj.has_tag? :example
+  
+  # Run examples
+  obj.tags(:example).each do |exs|
+    exs.text.split(/\n/).each do |ex|
+      begin
+        hash = eval("{ #{ex} }")
+        hash.keys.first.should == hash.values.first
+      rescue => e
+        raise e, "#{e.message}\nInvalid spec example in #{objname}:\n\n\t#{ex}\n"
+      end
+    end
+  end
+end
+
+include YARD

data/templates/default/attributes/html/header.erb

@@ -0,0 +1,35 @@
+<div class="section <%= generator_name %>">
+  <h1>Attributes</h1>
+
+  <% ['class', 'instance'].select {|s| object.attributes[s].length > 0 }.each do |scope| %>
+    <div class="<%= scope %>">
+      <h2><%= scope.capitalize %> Attributes</h2>
+      <table>
+      <% object.attributes[scope].sort_by {|o| o.to_s.downcase }.each do |name, rw| %>
+        <tr>
+          <th class="name"><%= h name %></td>
+          <td class="readwrite">
+            [<%= ['read', 'write'].map {|t| 
+                rw[t] && !rw[t].is_explicit? ? "<span id='#{anchor_for rw[t]}'>#{t[0,1].upcase}</span>" : t[0,1].upcase
+              }.compact.join %>] 
+          </td>
+          <td class="visibility">
+            <%= rw.values.compact.first.visibility %>
+          </td>
+          <td class="docstring">
+            <%= htmlify rw.values.compact.first.short_docstring %>
+            <% if rw[:read] && rw[:read].tag(:return) && rw[:read].tag(:return).types %>
+              <p class='returns'>
+                Returns: 
+                  <span class='return_types'>
+                     <%= format_return_types rw[:read] %>
+                  </span>
+              </p>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+      </table>
+    </div>
+  <% end %>
+</div>

data/templates/default/attributes/text/header.erb

@@ -0,0 +1,10 @@
+
+
+> Attributes:
+-------------
+<% ['class', 'instance'].select {|s| object.attributes[s].length > 0 }.each do |scope| %>
+<% object.attributes[scope].sort_by {|o| o.to_s.downcase }.each do |name, rw| %>
+<%= uml_visibility rw.values.compact.first %> <%= rw.values.compact.first.name(true) %><%= " " if scope == 'class' %>	[<%= ['read', 'write'].map {|t| rw[t] ? t[0,1].upcase : ' ' }.compact.join %>]	(<%= rw.values.compact.first.visibility %>)
+<% end %>
+<% end %>
+

data/templates/default/class/html/header.erb

@@ -0,0 +1,4 @@
+<div class="section class <%= object.path.gsub(/::|\.|#/, '_') %>">
+  <h1 class="title"><%= h format_object_type(object) %>: <%= h object.path %></h1>
+  <%= yield object %>
+</div>

data/templates/default/constants/html/constants.erb

@@ -0,0 +1,9 @@
+<div class="thisclass">
+  <h1>Constants</h1>
+  <dl>
+    <% object.constants(:included => false, :inherited => false).sort_by {|c| c.name.to_s.downcase }.each do |const| %>
+      <dt id="<%= anchor_for(const) %>"><%= h const.name %></dt>
+      <dd><%= h const.source.gsub(/\A.+?\=\s*/, '') %></dd>
+    <% end %>
+  </dl>
+</div>

data/templates/default/constants/html/header.erb

@@ -0,0 +1,3 @@
+<div class="section <%= generator_name %>">
+  <%= yield object %>
+</div>

data/templates/default/constants/html/included.erb

@@ -0,0 +1,9 @@
+<div class="included">
+  <% included_constants_by_module do |klass, consts| %>
+  <div>
+    <h1>Constants Included from <%= linkify klass %></h1>
+    <p><%= format_object_name_list consts %></p>
+  </div>
+  <% end %>
+</div>
+<div class="clear"></div>

data/templates/default/constants/html/inherited.erb

@@ -0,0 +1,9 @@
+<div class="inherited">
+  <% inherited_constants_by_class do |klass, consts| %>
+  <div>
+    <h1>Constants Inherited from <%= linkify klass %></h1>
+    <p><%= format_object_name_list consts %></p>
+  </div>
+  <% end %>
+</div>
+<div class="clear"></div>

data/templates/default/constructor/html/header.erb

@@ -0,0 +1,10 @@
+<div class="section <%= generator_name %>">
+<h1>Constructor Summary</h1>
+<% if constructor_method_inherited? %>
+  <p class="inherited_msg">
+    This class inherits a constructor from <%= linkify constructor_method, constructor_method.namespace.path %>.
+  </p>
+<% else %>
+  <%= yield constructor_method %>
+<% end %>
+</div>

data/templates/default/deprecated/html/main.erb

@@ -0,0 +1,4 @@
+<p class="section <%= generator_name %>">
+  <strong>Deprecated.</strong> <em><%= htmlify object.tag(:deprecated).text %></em>
+</p>
+

data/templates/default/deprecated/text/main.erb

@@ -0,0 +1,3 @@
+
+!! This <%= object.type %> is deprecated<%= object.tag(:deprecated).text ? ": " + object.tag(:deprecated).text : "" %>.
+

data/templates/default/docstring/html/main.erb

@@ -0,0 +1,3 @@
+<div class="section <%= generator_name %>">
+  <%= htmlify object.docstring %>
+</div>

data/templates/default/docstring/text/main.erb

@@ -0,0 +1,3 @@
+<%= object.docstring %>
+
+

data/templates/default/fulldoc/html/all_methods.erb

@@ -0,0 +1,25 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+  <head>
+    <%= render :html_head %>
+    <title>All Modules / Classes</title>
+    <base target="main" />
+  </head>
+  <body>
+    <div id="nav" class="methods">
+      <h1>Method List</h1>
+      <ul>
+      <% for obj in YARD::Registry.all(:method).sort_by {|o| o.path } %>
+        <% next if obj.namespace == Registry.root %>
+        <li nowrap>
+          <%= linkify(obj, (obj.scope == :class ? '' : '#') + obj.name.to_s) %> 
+          <% if obj.namespace != Registry.root %>
+            <em>(<%= obj.namespace.type %> <%= obj.namespace.name %>)</em>
+          <% end %>
+        </li>
+      <% end %>
+      </ul>
+    </div>
+  </body>
+</html>

data/templates/default/fulldoc/html/all_namespaces.erb

@@ -0,0 +1,19 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+  <head>
+    <%= render :html_head %>
+    <title>All Modules / Classes</title>
+    <base target="main" />
+  </head>
+  <body>
+    <div id="nav" class="namespaces">
+      <h1>All Modules / Classes</h1>
+      <ul>
+      <% for obj in YARD::Registry.all(:module, :class).sort_by {|o| o.path } %>
+        <li><%= linkify(obj) %> <em>(<%= obj.type %>)</em></li>
+      <% end %>
+      </ul>
+    </div>
+  </body>
+</html>

data/templates/default/fulldoc/html/app.js

@@ -0,0 +1,18 @@
+$(document).ready(function() {
+    // Set the title of this page as the index title
+    if (parent && parent.document) {
+        $('html head title', parent.document).text($('html head title').text());
+    }
+    
+    // Setup the view source links
+    $(".section.source a.source_link").toggle(
+        function() {
+            $(this).text('Hide source');
+            $(this).parent().next().show();
+        },
+        function() {
+            $(this).text('View source');
+            $(this).parent().next().hide();
+        }
+    );
+});

data/templates/default/fulldoc/html/header.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+  <head>
+    <%= render :html_head %>
+    <script src="<%= url_for(js_file) %>" type="text/javascript" charset="utf-8"></script>
+    <script src="<%= url_for(js_app_file) %>" type="text/javascript" charset="utf-8"></script>
+    <title><%= h format_object_type(object) %>: <%= h object.path %></title>
+  </head>
+  <body>
+    <div id="content">
+      <%= yield object %>
+    </div>
+  </body>
+</html>