yard 0.2.0 → 0.2.1

data/lib/source_parser.rb

@@ -51,11 +51,18 @@ module YARD
     
     private
       def top_level_parse(statements)
-        statements.each do |stmt|
-          find_handlers(stmt).each do |handler| 
-            handler.new(self, stmt).process
+          statements.each do |stmt|
+            find_handlers(stmt).each do |handler| 
+              begin
+                handler.new(self, stmt).process
+              rescue => e
+                STDERR.puts "#{handler.to_s} error in `#{file}`:#{stmt.tokens.first.line_no}: #{stmt.tokens.to_s}"
+                STDERR.puts "Exception message: #{e.message}"
+                STDERR.puts e.backtrace[0, 5]
+                STDERR.puts
+              end
+            end
           end
-        end
       end
     
       def find_handlers(stmt)
@@ -174,7 +181,7 @@ module YARD
               # 
               # if a ||
               #    b
-              if [EXPR_END, EXPR_ARG].include? last_tk.lex_state
+              if last_tk && [EXPR_END, EXPR_ARG].include?(last_tk.lex_state)
                 stmt_number += 1
                 new_statement = true
                 #p "NEW STATEMENT #{statement.to_s}"

data/lib/tag_library.rb

@@ -31,28 +31,41 @@ module YARD
   # @see TagLibrary::define_tag!
   module TagLibrary
     class << self
+      attr_reader :labels
+      
+      ## 
+      # Sorts the labels lexically by their label name, often used when displaying
+      # the tags.
+      # 
+      # @return [Array<Symbol,String>] the sorted labels as an array of the tag name and label
+      def sorted_labels
+        labels.sort_by {|a| a.last }
+      end
+      
       ##
       # 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.
       #
       # @param tag the tag name to create
       # @param meth the {Tag} factory method to call when creating the tag
-      def self.define_tag!(tag, meth = "")
+      def self.define_tag!(label, tag, meth = "")
         meth = meth.to_s
         send_name = meth.empty? ? "" : "_" + meth
         class_eval "def #{tag}_tag(text) Tag.parse_tag#{send_name}(#{tag.inspect}, text) end"
+        @labels ||= {}
+        @labels.update(tag => label)
       end
       
-      define_tag! :param, :with_types_and_name
-      define_tag! :yieldparam, :with_types_and_name
-      define_tag! :yield
-      define_tag! :return, :with_types
-      define_tag! :deprecated
-      define_tag! :author
-      define_tag! :raise, :with_name
-      define_tag! :see
-      define_tag! :since
-      define_tag! :version
+      define_tag! "Parameters",       :param,       :with_types_and_name
+      define_tag! "Block Parameters", :yieldparam,  :with_types_and_name
+      define_tag! "Yields",           :yield
+      define_tag! "Returns",          :return,      :with_types
+      define_tag! "Deprecated",       :deprecated
+      define_tag! "Author",           :author
+      define_tag! "Raises",           :raise,       :with_name
+      define_tag! "See Also",         :see
+      define_tag! "Since",            :since
+      define_tag! "Version",          :version
     end
   end
   

data/lib/yard.rb

@@ -1,3 +1,8 @@
-YARD_VERSION = "0.2.0"
+module YARD
+  VERSION = "0.2.1"
+end
+
+require File.dirname(__FILE__) + '/extra'
+require File.dirname(__FILE__) + '/logger'
 require File.dirname(__FILE__) + '/namespace'
 require File.dirname(__FILE__) + '/source_parser'

data/templates/default/html/_fulldoc.erb

@@ -0,0 +1,64 @@
+<% if tag("deprecated") %>
+<p><strong>Deprecated.</strong> <em><%= to_html tag("deprecated").text %></em></p>
+<% end %>
+<% if tag("yield") %>
+<p><strong>Yields Block.</strong> <em><%= to_html tag("yield").text %></em></p>
+<% end %>
+<p>
+  <%= to_html docstring %>
+</p>
+<% unless tags.empty? %>
+<dl>
+  <% unless tags("param").empty? %>
+  <dt>Parameters:</dt>
+  <dd>
+    <% tags("param").each do |tag| %>
+    <% unless tag.types.empty? %>
+      [<%= tag.types.collect {|t| "<tt>" + link_to_path(t, parent) + "</tt>" }.join(", ") %>]
+    <% end %>
+    <tt><%= tag.name %></tt> <%= "- " + to_html(tag.text) if tag.text %><br />
+    <% end %>
+  </dd>
+  <% end %>
+  <% unless tags("yieldparam").empty? %>
+  <dt>Yield Parameters:</dt>
+    <dd>
+    <% tags("yieldparam").each do |tag| %>
+      <% unless tag.types.empty? %>
+        [<%= tag.types.collect {|t| "<tt>" + link_to_path(t, parent) + "</tt>" }.join(", ") %>]
+      <% end %>
+      <tt><%= tag.name %></tt> <%= "- " + to_html(tag.text) if tag.text %><br />
+    <% end %>
+    </dd>
+  <% end %>
+  <% if has_tag?("return") %>
+  <dt>Returns:</dt>
+  <dd><%= to_html tag("return").text %></dd>
+  <% end %>
+  <% unless tags("raise").empty? %>
+  <dt>Raises:</dt>
+  <dd>
+    <% tags("raise").each do |tag| %>
+    <tt><%= link_to_path(tag.name, parent) %></tt> <%= "- " + to_html(tag.text) if tag.text %><br />
+    <% end %>
+  </dd>
+  <% end %>
+
+  <% if has_tag?("author") %>
+  <dt>Author:</dt>
+  <dd><%= to_html tag("author").text %></dd>
+  <% end %>
+  <% if has_tag?("version") %>
+  <dt>Version:</dt>
+  <dd><%= to_html tag("version").text %></dd>
+  <% end %>
+  <% if has_tag?("since") %>
+  <dt>Since:</dt>
+  <dd><%= to_html tag("since").text %></dd>
+  <% end %>
+  <% unless tags("see").empty? %>
+  <dt>See Also:</dt>
+  <dd><%= tags("see").collect {|t| "<tt>" + link_to_path(t.text, parent) + "</tt>" }.join(", ") %></dd>
+  <% end %>
+</dl>
+<% end %>

data/templates/default/html/class.erb

@@ -0,0 +1,226 @@
+<% _class_methods = class_methods.select {|k,m| m.visibility == :public }.sort %>
+<% _instance_methods = instance_methods.select {|k,m| m.visibility == :public && k != 'initialize' && k != 'method_missing' }.sort %>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+  <head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+    <title>Ruby documentation: <%= path %></title>
+    <style>
+    .topdoc * dt {
+      font-weight: bold;
+    }
+    .fulldoc {
+      margin-left: 37px;
+    }
+    .fulldoc * dt {
+      font-weight: bold;
+    }
+    h1 { color: #000; }
+    td { padding: 3px; }
+    </style>
+  <base target="_self" />
+  </head
+  <body>
+    <h1>Class <%= path %></h1>
+<% unless superclasses.empty? %>
+<pre>
+<% spaces = 0 -%>
+<% superclasses.reverse.each do |superclass| -%><%= (" " * spaces) + (spaces > 0 ? "+--" : "") + link_to_path(superclass) %>
+<% spaces += (spaces == 0 ? 2 : 4) -%><%= (" " * spaces) + "|" %>
+<% end -%><%= (" " * spaces ) + "+--" + path %>
+</pre> 
+<% end %>
+    
+    <% unless mixins.empty? %>
+    <p>
+      <strong>All Included Modules:</strong><br />
+      <%= "&nbsp;" * 7 %><%= mixins.collect {|m| link_to_path(m) }.join(", ") %>
+    </p>
+    <% end %>
+
+    <hr />  
+    
+    <% if docstring %>
+      <div class="topdoc">
+        <%= formatter.render('_fulldoc') %>
+      </div>
+      <hr />
+    <% end %>
+    
+    <% unless self[:attributes].empty? %>
+      <h1>Attributes</h1>
+      <p style="line-height:20px">
+      <% self[:attributes].sort.each do |name, rw| %>
+        <tt><%= name %> [<%= [(rw[:read] ? "R" : nil), (rw[:write] ? "W" : nil)].compact.join(", ") %>]</tt><br />
+      <% end %>
+      </p>
+    <% end %>
+    
+    <% displayed_constants = false %>
+    <% unless constants.empty? %>
+    <h1>Constants</h1><% displayed_constants = true %>
+    <dl>
+      <% constants.each do |name, constant| %>
+      <dt id="const-<%= name %>"><pre><%= constant.full_source.gsub(/\s+/,' ') %></pre></dt>
+      <dd><%= to_html constant.docstring %></dd>
+      <% end %>
+    </dl>
+    <% end %>
+    
+    <% inheritance_tree.each do |name| %>
+      <% superclass = Namespace.at(name) or next %>
+      <% unless (consts = superclass.constants).empty? %>
+      <% unless displayed_constants %><h1>Constants</h1><% end %>
+      <p><table border="1" width="100%">
+        <tr background="#ddddff">
+          <th>Constants <%= superclass.type == :module ? "included" : "inherited" %> from <%= link_to_path(superclass.path) %></th>
+        </tr>
+        <tr>
+          <td><%= consts.collect {|m| "<tt>" + link_to_path(m.first, superclass.path) + "</tt>" }.join(", ") %></td>
+        </tr>
+      </table></p>
+      <% end %>
+    <% end %>
+    
+    <% displayed_cvars = false %>
+    <% unless class_variables.empty? %>
+    <h1>Class Variables</h1><% displayed_cvars = true %>
+    <dl>
+    <% class_variables.each do |name, cvar| %>
+    <dt><pre><%= cvar.source.gsub(/\s+/,' ') %></pre></dt>
+    <dd><%= to_html cvar.docstring %></dd>
+    <% end %>
+    </dl>
+    <% end %>
+    
+    <% superclasses.each do |name| %>
+      <% superclass = Namespace.at(name) or next %>
+      <% unless (consts = superclass.class_variables.sort).empty? %>
+      <% unless displayed_cvars %><h1>Constants</h1><% end %>
+      <p><table border="1" width="100%">
+        <tr background="#ddddff">
+          <th>Class Variables inherited from <%= link_to_path(superclass.path) %></th>
+        </tr>
+        <tr>
+          <td><%= consts.reject {|name, cvar| class_variables.has_key? name }.
+                    collect {|name, cvar| "<tt>" + link_to_path(cvar, nil, name) + "</tt>" }.join(", ") %></td>
+        </tr>
+      </table></p>
+      <% end %>
+    <% end %>
+
+    <% if method = instance_methods['initialize'] %>
+    <h1>Constructor Summary</h1>
+    <tt>
+      <%= method.source.gsub(/\Adef\s+/, '')  %>
+      <% unless method.tags("yieldparam").empty? %>
+        {|<%= method.tags("yieldparam").collect {|t| t.name }.join(", ") %>| ... }
+      <% end %>  
+    </tt>
+      <%= method.to_s(format, template) %>
+    <% else %>
+      <% inheritance_tree.each do |name| %>
+        <% superclass = Namespace.at(name) or next %>
+        <% if method = superclass.instance_methods['initialize'] %>
+          <h1>Constructor Summary</h1>
+          <p>
+            <em>This class inherits a constructor from <tt><%= link_to_path(method.path, nil, method.parent.path) %></tt></em>
+          </p>
+          <% break %>
+        <% end %>
+      <% end %>
+    <% end %>
+    
+    <% if method = instance_methods['method_missing'] %>
+      <h1>Dynamic Method Handling</h1>
+      <p><em>This class handles dynamic methods through the <tt>method_missing</tt> method</em></p>
+      <%= method.to_s(format, template) %>
+    <% else %>
+      <% inheritance_tree.each do |name| %>
+        <% superclass = Namespace.at(name) or next %>
+        <% if method = superclass.instance_methods['method_missing'] %>
+          <h1>Dynamic Method Handling</h1>
+          <p>
+            <em>
+              This class handles dynamic methods through the 
+              <tt>
+              <%= link_to_path(method.path, nil, 'method_missing') %></tt> method in 
+              the <%= superclass.type %> <tt><%= link_to_path(superclass.path) %></tt>
+              </tt>
+            </em>
+          </p>
+          <% break %>
+        <% end %>
+      <% end %>
+    <% end %>
+
+    <% displayed_public_meth_summary = false %>
+    <% CodeObject::SCOPES.each do |scope| %>
+      <% unless eval("_#{scope}_methods").empty? %>
+      <% displayed_public_meth_summary = true %>
+      <h1>Public <%= scope.to_s.capitalize %> Method Summary</h1>
+      <table border="1" width="100%">
+        <% eval("_#{scope}_methods").each do |name, method| %>
+        <tr>
+          <td width="70" align="right" valign="top">
+            <small>
+              <% if method.tag("return") && method.tag("return").types %>
+              <%= method.tag("return").types.collect {|t| link_to_path(t) }.join(", ") %>
+              <% else %>
+              <%= ClassObject::BASE_OBJECT %>
+              <% end %>
+            </small>
+          </td>
+          <td>
+            <tt>
+              <%= method.source.sub(/\Adef\s+\S+?(\(|\s|;|$)/, link_to_path(method.path, nil, method.name) + '\1') if method.source %>
+              <% unless method.tags("yieldparam").empty? %>
+                {|<%= method.tags("yieldparam").collect {|t| t.name }.join(", ") %>| ... }
+              <% end %>  
+            </tt><br />
+            <%= ("&nbsp;" * 5) + to_html(method.docstring.sub(/(\.|\n).+/m,'')) + "." if method.docstring && !method.docstring.empty? %>
+            <% if method.tag("deprecated") %>
+            <br /><strong>Deprecated.</strong> <em><%= method.tag("deprecated").text %></em>
+            <% end %>
+          </td>
+        </tr>
+        <% end %>
+      </table>
+      <% end %>
+    
+      <% inheritance_tree.each do |name| %>
+        <% superclass = Namespace.at(name) or next %>
+        <% unless (meths = superclass.send("#{scope}_methods").select {|k,m| m.visibility == :public }).empty? %>
+          <% unless displayed_public_meth_summary %>
+          <h1>Public <%= scope.to_s.capitalize %> Method Summary</h1>
+          <% end %>
+        <p><table border="1" width="100%">
+          <tr background="#ddddff">
+            <th>
+              Public <%= scope %> methods <%= superclass.type == :module ? "included" : "inherited" %> 
+              from <%= link_to_path(superclass.path) %>
+            </th>
+          </tr>
+          <tr>
+            <td><%= superclass.send("#{scope}_methods").reject {|name, m| meths.include? name }.
+              collect {|name, m| "<tt>" + link_to_path(superclass.path + (scope == :instance ? "#" : "::") + 
+                          name, nil, name) + "</tt>" }.join(", ") %></td>
+          </tr>
+        </table></p>
+        <% end %>
+      <% end %>
+    <% end %>
+    
+    <% CodeObject::SCOPES.each do |scope| %>
+      <% unless eval("_#{scope}_methods").empty? %>
+        <h1>Public <%= scope.to_s.capitalize %> Method Details</h1>
+        <% eval("_#{scope}_methods").each do |name, method| %>
+          <%= method.to_s(format, template) %>
+          <hr />
+        <% end %>
+      <% end %>
+    <% end %>
+  </body>
+</html>

data/templates/default/html/method.erb

@@ -0,0 +1,20 @@
+<div id="<%= scope %>_method-<%= name %>">
+  <h3><%= name %></h3>
+  <% 
+  if tag("return") && !tag("return").types.empty? 
+    type = tag("return").types.collect {|t| link_to_path(t, parent) }.join(", ")
+    type = "[#{type}]" if tag("return").types.size > 1
+  else
+    type = ClassObject::BASE_OBJECT  
+  end
+  %>
+  <tt>
+    <%= source.gsub(/\Adef/, "#{visibility} " + type) if source %>
+    <% unless tags("yieldparam").empty? %>
+      {|<%= tags("yieldparam").map {|t| t.name }.join(", ") %>| ... }
+    <% end %>  
+  </tt>
+  <div class="fulldoc">  
+  <%= formatter.render('_fulldoc') %>
+  </div>
+</div>

data/templates/default/html/module.erb

@@ -0,0 +1,126 @@
+<% _class_methods = class_methods.select {|k,m| m.visibility == :public }.sort %>
+<% _instance_methods = instance_methods.select {|k,m| m.visibility == :public && k != 'initialize' && k != 'method_missing' }.sort %>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+  <head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+    <title>Ruby documentation: <%= path %></title>
+    <style>
+    .topdoc * dt {
+      font-weight: bold;
+    }
+    .fulldoc {
+      margin-left: 37px;
+    }
+    .fulldoc * dt {
+      font-weight: bold;
+    }
+    h1 { color: #000; }
+    td { padding: 3px; }
+    </style>
+  <base target="_self" />
+  </head>
+  <body>
+    <h1>Module <%= path %></h1>
+  
+    <% if mixins && !mixins.empty? %>
+    <p>
+      <strong>All Included Modules:</strong><br />
+      <%= "&nbsp;" * 7 %><%= mixins.collect {|m| link_to_path(m) }.join(", ") %>
+    </p>
+    <% end %>
+
+    <hr />  
+    
+    <% if docstring %>
+      <div class="topdoc">
+        <%= formatter.render('_fulldoc') %>
+      </div>
+      <hr />
+    <% end %>
+    
+    <% if self[:attributes] && !self[:attributes].empty? %>
+      <h1>Attributes</h1>
+      <p style="line-height:20px">
+      <% self[:attributes].sort.each do |name, rw| %>
+        <tt><%= name %> [<%= [(rw[:read] ? "R" : nil), (rw[:write] ? "W" : nil)].compact.join(", ") %>]</tt><br />
+      <% end %>
+      </p>
+    <% end %>
+    
+    <% displayed_constants = false %>
+    <% if constants && !constants.empty? %>
+    <h1>Constants</h1><% displayed_constants = true %>
+    <dl>
+      <% constants.each do |name, constant| %>
+      <dt id="const-<%= name %>"><pre><%= constant.full_source.gsub(/\s+/,' ') %></pre></dt>
+      <dd><%= to_html constant.docstring %></dd>
+      <% end %>
+    </dl>
+    <% end %>
+    
+    <% if method = instance_methods['initialize'] %>
+    <h1>Constructor Summary</h1>
+    <tt>
+      <%= method.source.gsub(/\Adef\s+/, '')  %>
+      <% unless method.tags("yieldparam").empty? %>
+        {|<%= method.tags("yieldparam").collect {|t| t.name }.join(", ") %>| ... }
+      <% end %>  
+    </tt>
+      <%= method.to_s(format, template) %>
+    <% end %>
+    
+    <% if method = instance_methods['method_missing'] %>
+      <h1>Dynamic Method Handling</h1>
+      <p><em>This class handles dynamic methods through the <tt>method_missing</tt> method</em></p>
+      <%= method.to_s(format, template) %>
+    <% end %>
+
+    <% displayed_public_meth_summary = false %>
+    <% CodeObject::SCOPES.each do |scope| %>
+      <% unless eval("_#{scope}_methods").empty? %>
+      <% displayed_public_meth_summary = true %>
+      <h1>Public <%= scope.to_s.capitalize %> Method Summary</h1>
+      <table border="1" width="100%">
+        <% eval("_#{scope}_methods").each do |name, method| %>
+        <tr>
+          <td width="70" align="right" valign="top">
+            <small>
+              <% if method.tag("return") && method.tag("return").types %>
+              <%= method.tag("return").types.collect {|t| link_to_path(t) }.join(", ") %>
+              <% else %>
+              <%= ClassObject::BASE_OBJECT %>
+              <% end %>
+            </small>
+          </td>
+          <td>
+            <tt>
+              <%= method.source.sub(/\Adef\s+\S+?(\(|\s|;|$)/, link_to_path(method.path, nil, method.name) + '\1') if method.source %>
+              <% unless method.tags("yieldparam").empty? %>
+                {|<%= method.tags("yieldparam").collect {|t| t.name }.join(", ") %>| ... }
+              <% end %>  
+            </tt><br />
+            <%= ("&nbsp;" * 5) + to_html(method.docstring.sub(/(\.|\n).+/m,'')) + "." if method.docstring && !method.docstring.empty? %>
+            <% if method.tag("deprecated") %>
+            <br /><strong>Deprecated.</strong> <em><%= method.tag("deprecated").text %></em>
+            <% end %>
+          </td>
+        </tr>
+        <% end %>
+        </table>
+      <% end %>
+    <% end %>
+    
+    <% CodeObject::SCOPES.each do |scope| %>
+      <% unless eval("_#{scope}_methods").empty? %>
+        <h1>Public <%= scope.to_s.capitalize %> Method Details</h1>
+        <% eval("_#{scope}_methods").each do |name, method| %>
+          <%= method.to_s(format, template) %>
+          <hr />
+        <% end %>
+      <% end %>
+    <% end %>
+  </body>
+</html>