jakewendt-rdoc_rails 0.0.2

data/README.rdoc

@@ -0,0 +1,94 @@
+= RDoc::Rails
+
+This package adds Rails-specific information to RDoc generated docs on Rails
+projects. It could be particularly useful for people wanting to document Rails
+applications for internal use within a team of developers. It includes
+<tt>RDoc::Parser::Rails</tt> based on <tt>RDoc::Parser::Ruby</tt> as well as
+<tt>RDoc::Generator::Railsfish</tt> based on <tt>RDoc::Generator::Darkfish</tt>
+
+== Installation
+Currently, this is written as a Rails plugin, although I will look into
+packaging it as a gem as well. It works with RDoc version 2.4.3, the most
+current version as of August, 2009. I have tested it only with Rails 2.0, but I
+would expect it to work for projects written in earlier and later versions of
+Rails as well.
+
+To install as a Rails plugin, try some variation on one of the following:
+  ruby script/plugin install git://github.com/chinasaur/rdoc_rails.git
+  ruby script/plugin install http://github.com/chinasaur/rdoc_rails.git
+  ruby script/plugin install http://github.com/chinasaur/rdoc_rails.git/
+
+You may then need/want to rename the directory
+<tt>vendor/plugins/rdoc_rails.git/</tt> to just +rdoc_rails+
+
+After that, you should be good to go.  The standard
+ > rake doc:app
+or
+ > rake doc:reapp
+should now run the Rails customized version of RDoc.
+
+== Features
+Right now there are just two basic features above and beyond the standard Ruby
+RDoc:
+
+1. Documentation for ActiveRecord associations on Models
+2. Documentation for methods delegated to other models through the +delegate+ method.
+
+But the infrastructure is all there to make it straightforward to parse
+additional features in Rails code and generate documentation based on those
+parsings.
+
+== Suggested Features
+
+* named_scope parsing
+* validate_* parsing
+* before_* parsing
+* after_* parsing
+* attr_protected parsing
+* attr_accessible parsing
+* custom user grouping and parsing (probably more core rdoc)
+
+== Tests
+
+* Tests are in development
+* Both tests for Comment model's belongs_to associations fail
+  * one is polymorphic
+  * the other has a redefined class_name and counter_cache => true
+* tests run, but I don't parse the output yet
+
+
+== Contributing
+I will try to document things better to make it easy for others to contribute
+additional documentation features. For now, get in touch if you have any
+questions and fork away.
+
+== License http://i.creativecommons.org/l/by/3.0/us/80x15.png
+Rdoc::Rails is released under a {Creative Commons Attribution 3.0 United States
+License}[http://creativecommons.org/licenses/by/3.0/us/]. Please credit me
+somewhere in your project's documentation if you are using this.
+
+
+
+
+
+== Dev by Jake
+
+Gemified with Jeweler
+
+rake version:bump:patch  
+rake version:bump:minor
+rake version:bump:major
+
+rake gemspec
+
+rake install
+
+rake release
+
+
+This seems to be incompatible with the latest rdoc 3.4.
+Attempting to remedy.
+Still not working.
+
+
+

data/lib/jakewendt-rdoc_rails.rb

@@ -0,0 +1 @@
+require 'rdoc_rails'

data/lib/rdoc_rails.rb

@@ -0,0 +1,8 @@
+$: << File.expand_path(File.dirname(__FILE__))
+
+require 'rdoc_rails/rake'
+require 'rdoc_rails/rdoc/context'
+require 'rdoc_rails/rdoc/token_stream'
+require 'rdoc_rails/rdoc/ar_association'
+require 'rdoc_rails/rdoc/parser/rails'
+require 'rdoc_rails/rdoc/generator/railsfish'

data/lib/rdoc_rails/rake.rb

@@ -0,0 +1,21 @@
+module Rake
+  def self.remove_task(task_name)
+    Rake.application.instance_variable_get(:@tasks).delete(task_name.to_s) || raise('No such task!')
+  end
+  
+  class RDocTask
+    def self.remove_task(task='rdoc', opts={})
+      Rake.remove_task(Rake::Task[task].prerequisites[0])
+      Rake.remove_task(task)
+      
+      task = task.to_s.split(':')
+      name = task[-1]
+      path = task[0..-2] * ':'
+      rerdoc  = opts[:rerdoc]       || "re#{name}"
+      clobber = opts[:clobber_rdoc] || "clobber_#{name}"
+      
+      Rake.remove_task("#{path}:#{rerdoc}")
+      Rake.remove_task("#{path}:#{clobber}")
+    end
+  end
+end

data/lib/rdoc_rails/rdoc/ar_association.rb

@@ -0,0 +1,103 @@
+require 'active_support'
+require 'active_support/inflector'
+
+require 'cgi'
+class CGI
+	def self.escapeHTML_with_nil_check(string)
+		string = '' if string.nil?
+		escapeHTML_without_nil_check(string)
+	end
+	class << self
+		alias_method_chain :escapeHTML, :nil_check
+	end
+end
+
+class RDoc::ArAssociation < RDoc::Context
+  include RDoc::TokenStream
+  attr_accessor :atype
+  attr_accessor :name
+  attr_writer   :opts
+  
+  def initialize(init={})
+    super()
+    init.each{ |k,v| send("#{k}=", v) }
+  end
+  
+  def opts
+    @opts || {}
+  end
+  
+  def class_name
+    class_name   = opts[:class_name]
+    class_name ||= ActiveSupport::Inflector.classify(name) if ['has_many', 'has_and_belongs_to_many'].include?(atype.to_s)
+    class_name ||= name.camelize
+    class_name
+  end
+  
+  def path
+    parent.path
+  end
+  
+  # Pulled from RDoc::Generator::Markup
+  # Would be nice if this were moved into a module so it could be includable
+  # without copy/paste.
+  def add_line_numbers(src)
+    if src =~ /\A.*, line (\d+)/ then
+      first = $1.to_i - 1
+      last  = first + src.count("\n")
+      size = last.to_s.length
+      
+      line = first
+      src.gsub!(/^/) do
+        res = if line == first
+                " " * (size + 2)
+              else
+                "%#{size}d: " % line
+              end
+        
+        line += 1
+        res
+      end
+    end
+  end
+
+  # Pulled from RDoc::Generator::Markup
+  # Would be nice if this were moved into a module so it could be includable
+  # without copy/paste.
+  def markup_code
+    return '' unless @token_stream
+    
+    src = ""
+    
+    @token_stream.each do |t|
+      next unless t
+      #        style = STYLE_MAP[t.class]
+      style = case t
+                when RDoc::RubyToken::TkCONSTANT then "ruby-constant"
+                when RDoc::RubyToken::TkKW       then "ruby-keyword kw"
+                when RDoc::RubyToken::TkIVAR     then "ruby-ivar"
+                when RDoc::RubyToken::TkOp       then "ruby-operator"
+                when RDoc::RubyToken::TkId       then "ruby-identifier"
+                when RDoc::RubyToken::TkNode     then "ruby-node"
+                when RDoc::RubyToken::TkCOMMENT  then "ruby-comment cmt"
+                when RDoc::RubyToken::TkREGEXP   then "ruby-regexp re"
+                when RDoc::RubyToken::TkSTRING   then "ruby-value str"
+                when RDoc::RubyToken::TkVal      then "ruby-value"
+                else nil
+              end
+      
+      text = CGI.escapeHTML(t.text)
+      
+      if style
+        src << "<span class=\"#{style}\">#{text}</span>"
+      else
+        src << text
+      end
+    end
+    
+#    add_line_numbers src if RDoc::RDoc.current.options.include_line_numbers
+# change for rdoc > 2.4.3
+    
+    src
+  end
+end

data/lib/rdoc_rails/rdoc/context.rb

@@ -0,0 +1,19 @@
+require 'rdoc/context'
+class RDoc::Context
+  attr_accessor :ar_associations
+  
+  # Overriding to initialize ar_associations
+  def initialize_methods_etc
+    @method_list = []
+    @attributes  = []
+    @aliases     = []
+    @requires    = []
+    @includes    = []
+    @constants   = []
+    @ar_associations = []
+    
+    # This Hash maps a method name to a list of unmatched aliases (aliases of
+    # a method not yet encountered).
+    @unmatched_alias_lists = {}
+  end
+end

data/lib/rdoc_rails/rdoc/generator/railsfish.rb

@@ -0,0 +1,27 @@
+require 'rdoc/generator/darkfish'
+class RDoc::Generator::Railsfish < RDoc::Generator::Darkfish
+  RDoc::RDoc.add_generator(self)
+  VERSION = '0.1.0'
+  
+  # Override template path to use standard darkfish template for most pages
+  def initialize(opts)
+    opts.instance_variable_set(:@template, 'darkfish') if opts.template == 'railsfish'
+    super
+  end
+  
+  # Overriding to allow setting templatefile to my Rails customized version.
+  def generate_class_files
+    debug_msg "Generating class documentation in #@outputdir"
+    templatefile = Pathname.new(File.dirname(__FILE__) + '/template/railsfish/classpage.rhtml')
+    
+    @classes.each do |klass|
+      debug_msg "  working on %s (%s)" % [ klass.full_name, klass.path ]
+      outfile    = @outputdir + klass.path
+      rel_prefix = @outputdir.relative_path_from( outfile.dirname )
+      svninfo    = self.get_svninfo( klass )
+      
+      debug_msg "  rendering #{outfile}"
+      self.render_template( templatefile, binding(), outfile )
+    end
+  end
+end

data/lib/rdoc_rails/rdoc/generator/template/railsfish/classpage.rhtml

@@ -0,0 +1,308 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <meta content="text/html; charset=<%= @options.charset %>" http-equiv="Content-Type" />
+  
+  <title><%= klass.type.capitalize %>: <%= klass.full_name %></title>
+  
+  <link rel="stylesheet" href="<%= rel_prefix %>/rdoc.css" type="text/css" media="screen" />
+  
+  <script src="<%= rel_prefix %>/js/jquery.js" type="text/javascript" charset="utf-8"></script>
+  <script src="<%= rel_prefix %>/js/thickbox-compressed.js" type="text/javascript" charset="utf-8"></script>
+  <script src="<%= rel_prefix %>/js/quicksearch.js" type="text/javascript" charset="utf-8"></script>
+  <script src="<%= rel_prefix %>/js/darkfish.js" type="text/javascript" charset="utf-8"></script>
+  
+</head>
+
+<body class="<%= klass.type %>">
+  
+  <div id="metadata">
+    <div id="file-metadata">
+      <div id="file-list-section" class="section">
+        <h3 class="section-header">In Files</h3>
+        <div class="section-body">
+          <ul>
+            <% klass.in_files.each do |tl| %>
+              <li><a href="<%= rel_prefix %>/<%= h tl.path %>?TB_iframe=true&amp;height=550&amp;width=785"
+                class="thickbox" title="<%= h tl.absolute_name %>"><%= h tl.absolute_name %></a></li>
+            <% end %>
+          </ul>
+        </div>
+      </div>
+      
+      <% if !svninfo.empty? %>
+        <div id="file-svninfo-section" class="section">
+          <h3 class="section-header">Subversion Info</h3>
+          <div class="section-body">
+            <dl class="svninfo">
+              <dt>Rev</dt>
+              <dd><%= svninfo[:rev] %></dd>
+              
+              <dt>Last Checked In</dt>
+              <dd><%= svninfo[:commitdate].strftime('%Y-%m-%d %H:%M:%S') %>
+                (<%= svninfo[:commitdelta] %> ago)</dd>
+              
+              <dt>Checked in by</dt>
+              <dd><%= svninfo[:committer] %></dd>
+            </dl>
+          </div>
+        </div>
+      <% end %>
+    </div>
+    
+    <div id="class-metadata">
+      
+      <!-- Parent Class -->
+      <% if klass.type == 'class' %>
+        <div id="parent-class-section" class="section">
+          <h3 class="section-header">Parent</h3>
+          <% unless String === klass.superclass %>
+            <p class="link"><a href="<%= klass.aref_to klass.superclass.path %>"><%= klass.superclass.full_name %></a></p>
+          <% else %>
+            <p class="link"><%= klass.superclass %></p>
+          <% end %>
+        </div>
+      <% end %>
+      
+      <!-- Namespace Contents -->
+      <% unless klass.classes_and_modules.empty? %>
+        <div id="namespace-list-section" class="section">
+          <h3 class="section-header">Namespace</h3>
+          <ul class="link-list">
+            <% (klass.modules.sort + klass.classes.sort).each do |mod| %>
+              <li><span class="type"><%= mod.type.upcase %></span> <a href="<%= klass.aref_to mod.path %>"><%= mod.full_name %></a></li>
+            <% end %>
+          </ul>
+        </div>
+      <% end %>
+      
+      <!-- Method Quickref -->
+      <% unless klass.method_list.empty? %>
+        <div id="method-list-section" class="section">
+          <h3 class="section-header">Methods</h3>
+          <ul class="link-list">
+            <% klass.each_method do |meth| %>
+              <li><a href="#<%= meth.aref %>"><%= meth.singleton ? '::' : '#' %><%= meth.name %></a></li>
+            <% end %>
+          </ul>
+        </div>
+      <% end %>
+      
+      <!-- Included Modules -->
+      <% unless klass.includes.empty? %>
+        <div id="includes-section" class="section">
+          <h3 class="section-header">Included Modules</h3>
+          <ul class="link-list">
+            <% klass.each_include do |inc| %>
+              <% unless String === inc.module %>
+                <li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a></li>
+              <% else %>
+                <li><span class="include"><%= inc.name %></span></li>
+              <% end %>
+            <% end %>
+          </ul>
+        </div>
+      <% end %>
+    </div>
+    
+    <div id="project-metadata">
+      <% simple_files = @files.select {|tl| tl.parser == RDoc::Parser::Simple } %>
+      <% unless simple_files.empty? then %>
+        <div id="fileindex-section" class="section project-section">
+          <h3 class="section-header">Files</h3>
+          <ul>
+            <% simple_files.each do |file| %>
+              <li class="file"><a href="<%= rel_prefix %>/<%= file.path %>"><%= h file.base_name %></a></li>
+            <% end %>
+          </ul>
+        </div>
+      <% end %>
+      
+      <div id="classindex-section" class="section project-section">
+        <h3 class="section-header">Class Index
+          <span class="search-toggle">
+            <img src="<%= rel_prefix %>/images/find.png"
+              height="16" width="16" alt="[+]"
+              title="show/hide quicksearch" />
+          </span>
+        </h3>
+        <form action="#" method="get" accept-charset="utf-8" class="initially-hidden">
+          <fieldset>
+            <legend>Quicksearch</legend>
+            <input type="text" name="quicksearch" value="" class="quicksearch-field" />
+          </fieldset>
+        </form>
+        
+        <ul class="link-list">
+          <% @modsort.each do |index_klass| %>
+            <li><a href="<%= rel_prefix %>/<%= index_klass.path %>"><%= index_klass.full_name %></a></li>
+          <% end %>
+        </ul>
+        <div id="no-class-search-results" style="display: none;">No matching classes.</div>
+      </div>
+      
+      <% if $DEBUG_RDOC %>
+        <div id="debugging-toggle"><img src="<%= rel_prefix %>/images/bug.png"
+          alt="toggle debugging" height="16" width="16" /></div>
+      <% end %>
+    </div>
+  </div>
+  
+  <div id="documentation">
+    <h1 class="<%= klass.type %>"><%= klass.full_name %></h1>
+    
+    <div id="description"><%= klass.description %></div>
+    
+    <!-- Constants -->
+    <% unless klass.constants.empty? %>
+      <div id="constants-list" class="section">
+        <h3 class="section-header">Constants</h3>
+        <dl>
+          <% klass.each_constant do |const| %>
+            <dt><a name="<%= const.name %>"><%= const.name %></a></dt>
+            <% if const.comment %>
+              <dd class="description"><%= const.description.strip %></dd>
+            <% else %>
+              <dd class="description missing-docs">(Not documented)</dd>
+            <% end %>
+          <% end %>
+        </dl>
+      </div>
+    <% end %>
+    
+    <!-- Attributes -->
+    <% unless klass.attributes.empty? %>
+      <div id="attribute-method-details" class="method-section section">
+        <h3 class="section-header">Attributes</h3>
+        
+        <% klass.each_attribute do |attrib| %>
+          <div id="<%= attrib.html_name %>-attribute-method" class="method-detail">
+            <a name="<%= h attrib.name %>"></a>
+            <% if attrib.rw =~ /w/i %>
+              <a name="<%= h attrib.name %>="></a>
+            <% end %>
+            <div class="method-heading attribute-method-heading">
+              <span class="method-name"><%= h attrib.name %></span>
+              <span class="attribute-access-type">[<%= attrib.rw %>]</span>
+            </div>
+            
+            <div class="method-description">
+              <% if attrib.comment %>
+                <%= attrib.description.strip %>
+              <% else %>
+                <p class="missing-docs">(Not documented)</p>
+              <% end %>
+            </div>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+    
+    <!-- ActiveRecord Associations -->
+    <% unless klass.ar_associations.empty? %>
+      <div id="ara-method-details" class="method-section section">
+        <h3 class="section-header">ActiveRecord Associations</h3>
+        <% klass.ar_associations.each do |ara| %>
+          <div id="<%= ara.name %>-ara-method" class="method-detail">
+            <div class="method-heading ara-method-heading">
+              <span class="method-name">
+                <%= %Q|#{ara.atype} #{h ara.name} (<a href="#{ara.class_name}.html"><tt>#{ara.class_name}</tt></a>)| %>
+              </span>
+              <% if ara.token_stream %>
+                <span class="method-click-advice">click to toggle source</span>
+              <% end %>
+            </div>
+            
+            <div class="method-description">
+              <% if ara.comment %>
+                <%= ara.description.strip %>
+              <% end %>
+              
+              <% if ara.token_stream %>
+                <div class="method-source-code" id="<%= ara.name %>-source">
+                  <pre>
+<%= ara.markup_code %>
+                  </pre>
+                </div>
+              <% end %>
+            </div>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+    
+    <!-- Methods -->
+    <% klass.methods_by_type.each do |type, visibilities|
+      next if visibilities.empty?
+      visibilities.each do |visibility, methods|
+        next if methods.empty? %>
+        <div id="<%= visibility %>-<%= type %>-method-details" class="method-section section">
+          <h3 class="section-header"><%= visibility.to_s.capitalize %> <%= type.capitalize %> Methods</h3>
+          
+          <% methods.each do |method| %>
+            <div id="<%= method.html_name %>-method" class="method-detail <%= method.is_alias_for ? "method-alias" : '' %>">
+              <a name="<%= h method.aref %>"></a>
+              
+              <div class="method-heading">
+                <% if method.call_seq %>
+                  <span class="method-callseq"><%= method.call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w.*?\./m, '') %></span>
+                  <span class="method-click-advice">click to toggle source</span>
+                <% else %>
+                  <span class="method-name"><%= h method.name %></span>
+                  <span class="method-args"><%= method.params %></span>
+                  <span class="method-click-advice">click to toggle source</span>
+                <% end %>
+              </div>
+              
+              <div class="method-description">
+                <% if method.comment %>
+                  <%= method.description.strip %>
+                <% else %>
+                  <p class="missing-docs">(Not documented)</p>
+                <% end %>
+                
+                <% if method.token_stream %>
+                  <div class="method-source-code" id="<%= method.html_name %>-source">
+                    <pre>
+<%= method.markup_code %>
+                    </pre>
+                  </div>
+                <% end %>
+              </div>
+              
+              <% unless method.aliases.empty? %>
+                <div class="aliases">
+                  Also aliased as: <%= method.aliases.map do |aka|
+                    %{<a href="#{ klass.aref_to aka.path}">#{h aka.name}</a>}
+                  end.join(", ") %>
+                </div>
+              <% end %>
+            </div>
+            
+          <% end %>
+        </div>
+      <% end %>
+    <% end %>
+    
+    <div id="rdoc-debugging-section-dump" class="debugging-section">
+      <% if $DEBUG_RDOC
+        require 'pp' %>
+<pre><%= h PP.pp(klass, _erbout) %></pre>
+      <% else %>
+        <p>Disabled; run with --debug to generate this.</p>
+      <% end %>
+    </div>
+    
+  </div>
+  
+  <div id="validator-badges">
+    <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
+    <p><small>Generated with the Railsfish Rdoc Generator
+      <%= RDoc::Generator::Railsfish::VERSION %></small>.</p>
+  </div>
+  
+</body>
+</html>
+

data/lib/rdoc_rails/rdoc/parser/rails.rb

@@ -0,0 +1,387 @@
+require 'rdoc/parser/ruby'
+class RDoc::Parser::Rails < RDoc::Parser::Ruby
+  include RDoc::RubyToken
+  parse_files_matching(/\.rbw?$/)
+  
+  def parse_rails_meta(container, single, tk, comment)
+    return unless container.document_children
+    restore_init_token(tk)
+    # Start listening to get_tk and saving read tokens into @token_stream, parse
+    # symbol args
+    add_token_listener self
+    args = parse_symbol_arg # This gets any symbol or string args
+    opts = (parse_final_hash if token_stream[-1].is_a?(TkCOMMA)) || {}
+    remove_token_listener self
+    
+    send("parse_#{tk.name}", container, single, tk, comment, args, opts)
+  end
+  
+  def parse_rails_debug(container, single, tk, comment, args, opts)
+    puts tk.name
+    puts args.inspect
+    puts opts.inspect if opts
+    puts ""
+  end
+  
+  def parse_rails_pending(container, single, tk, comment, args, opts); end
+  alias parse_validates_uniqueness_of parse_rails_pending
+  
+  def parse_ar_association(container, single, tk, comment, args, opts)
+    ara =  RDoc::ArAssociation.new(
+      :atype   => tk.name,
+      :name    => args[0],
+      :opts    => opts,
+      :comment => comment
+    )
+    
+    ara.start_collecting_tokens
+    ara.add_tokens [position_comment(tk), NEWLINE_TOKEN]
+    ara.add_tokens token_stream
+    
+    ara.parent = container
+    container.ar_associations << ara
+  end
+  alias parse_belongs_to                parse_ar_association
+  alias parse_has_one                   parse_ar_association
+  alias parse_has_many                  parse_ar_association
+  alias parse_has_and_belongs_to_many   parse_ar_association
+  
+  # Take the args, opts, and tokens collected by parse_rails_meta and generate
+  # method documentation for delegated methods.
+  def parse_delegate(container, single, tk, comment, args, opts)
+    add_token_listener self
+    skip_to_eol
+    remove_token_listener self
+    
+    args.each do |arg|
+      d_meth = RDoc::AnyMethod.new('', arg)
+      @stats.add_method    d_meth
+      container.add_method d_meth
+      
+      d_meth.start_collecting_tokens
+      d_meth.add_tokens [position_comment(tk), NEWLINE_TOKEN]
+      d_meth.add_tokens token_stream
+      
+      d_meth.params   = "(?) - delegated to #{opts[:to].inspect}" if opts[:to]
+      d_meth.params ||= '(?) - delegated method...'
+      
+      d_meth.comment = comment
+    end
+  end
+  
+  def skip_to_eol
+    tk = get_tk until tk.is_a?(TkNL)
+  end
+  
+  # Parse tokens assumed to represent a final hash argument, thus will parse
+  # either a {} enclosed hash or a naked final hash.
+  #
+  # The purpose of this is mainly to be able to generate documentation for Rails
+  # meta calls, which generally have symbols/strings for keys and values, so
+  # that is what I've prioritized being able to parse. Shouldn't be difficult to
+  # add parsing of numeric keys/values. Parsing array/hash keys/values would be
+  # more difficult and isn't in the scope of what I currently plan to do.  If
+  # this hits something it doesn't know how to parse, it rewinds all its tokens
+  # and quits.
+  #
+  # The best way to set up a call to parse_final_hash is as is done in
+  # parse_rails_meta, where we first call parse_symbol_arg. This is good setup
+  # because parse_symbol_arg will rewind to the comma before the final hash if
+  # it detects a hash in parsing other args.
+  def parse_final_hash
+    buffer = TokenStream.new
+    add_token_listener(buffer)
+    skip_tkspace(true)
+    
+    case tk = get_tk
+      when TkLBRACE           then bracketed = true
+      when TkSYMBOL, TkSTRING then bracketed = false
+      else
+        unget_tk(tk) until buffer.token_stream.empty?
+        remove_token_listener(buffer)
+        return
+    end
+    
+    last_tk = tk
+    while tk = get_tk do
+      case tk
+        when TkSEMICOLON then break
+        when TkNL
+          unget_tk(tk) and break unless last_tk and TkCOMMA === last_tk
+        when TkSPACE, TkCOMMENT
+        when TkSYMBOL, TkSTRING, TkCOMMA, TkASSIGN, TkGT, TkASSOC then last_tk = tk # Will probably want to expand this to include numerics, possibly others; let's cross that bridge when we come to it.
+        else
+          break                  if  bracketed and tk.is_a?(TkRBRACE)
+          unget_tk(tk) and break if !bracketed and tk.is_a?(TkDO)
+          
+          unget_tk(tk) until buffer.token_stream.empty?
+          remove_token_listener(buffer)
+          return
+      end
+    end
+    
+    remove_token_listener(buffer)
+    read = buffer.token_stream.collect{|tk|tk.text}.join
+    read = "{#{read}\n}" if !bracketed # We need the \n in case #{read} ends with a comment
+    eval(read) rescue nil
+  end
+  
+  # Largely copied from super, but rewinds if it hits a =>, indicating the last
+  # symbol/string read should have been part of the final hash arg.  Rewinds to
+  # the comma before the final hash, which provides a good check after we return
+  # of whether there are still more arguments to parse.
+  def parse_symbol_arg(no=nil)
+    buffer = TokenStream.new
+    add_token_listener(buffer)
+    
+    args = []
+    skip_tkspace_comment
+    case tk = get_tk
+    when TkLPAREN
+      loop do
+        skip_tkspace_comment
+        if tk = parse_symbol_in_arg
+          args.push tk
+          break if no and args.size >= no
+        end
+        
+        skip_tkspace_comment
+        case tk2 = get_tk
+        when TkRPAREN
+          break
+        when TkCOMMA
+        when TkASSOC, TkASSIGN, TkGT
+          # Oops, we started slurping the final Hash!
+          # So rewind back past the symbol or string that came before the =>
+          unget_tk(buffer.token_stream[-1]) until buffer.token_stream[-1].is_a?(TkCOMMA) or buffer.token_stream.empty?
+          args.pop
+          break
+        when TkLBRACE
+          # We hit the beginning of a hash or block, so rewind to the comma
+          unget_tk(buffer.token_stream[-1]) until buffer.token_stream[-1].is_a?(TkCOMMA) or buffer.token_stream.empty?
+          break
+        else
+          warn("unexpected token: '#{tk2.inspect}'") if $DEBUG_RDOC
+          break
+        end
+      end
+    else
+      unget_tk tk
+      if tk = parse_symbol_in_arg
+        args.push tk
+        return args if no and args.size >= no
+      end
+      
+      loop do
+        skip_tkspace(false)
+        
+        tk1 = get_tk
+        if TkCOMMA === tk1
+        elsif TkASSOC === tk1 or TkASSIGN === tk1 or TkGT === tk1
+          # Oops, we started slurping the final Hash!
+          # So rewind back past the symbol or string that came before the =>
+          unget_tk(buffer.token_stream[-1]) until buffer.token_stream[-1].is_a?(TkCOMMA) or buffer.token_stream.empty?
+          args.pop
+          break
+        elsif TkLBRACE === tk1
+          # We hit the beginning of a hash or block, so rewind to the comma
+          unget_tk(buffer.token_stream[-1]) until buffer.token_stream[-1].is_a?(TkCOMMA) or buffer.token_stream.empty?
+          break
+        else
+          unget_tk tk1
+          break
+        end
+        
+        skip_tkspace_comment
+        if tk = parse_symbol_in_arg
+          args.push tk
+          break if no and args.size >= no
+        end
+      end
+    end
+    
+    remove_token_listener buffer
+    args
+  end
+  
+  # Comment line required to help generator put line numbers on included source code.
+  def position_comment(tk)
+    TkCOMMENT.new(tk.line_no, 1, "# File #{@top_level.absolute_name}, line #{tk.line_no}")
+  end
+  
+  # Clear @token_stream and then put back the indentation and initial token;
+  # basically assumes tk is the first non-whitespace token on the line.
+  def restore_init_token(tk)
+    start_collecting_tokens
+#    indent = TkSPACE.new(1, 1)
+#	change for rdoc > 2.4.3
+    indent = TkSPACE.new(nil,1, 1)
+    indent.set_text(' ' * tk.char_no)
+    add_tokens([indent, tk])
+  end
+  
+  # The identifiers that should be processed as rails meta-calls
+  RAILS_IDENTIFIERS = [
+    'belongs_to',
+    'has_one',
+    'has_many',
+    'has_and_belongs_to_many',
+    'delegate',
+    'validates_uniqueness_of'
+  ]
+
+  # Copied from super, with a minor tweak to the TkIDENTIFIER parsing portion.
+  def parse_statements(container, single = NORMAL, current_method = nil, comment = '')
+    nest = 1
+    save_visibility = container.visibility
+    
+    non_comment_seen = true
+    
+    while tk = get_tk do
+      keep_comment = false
+      
+      non_comment_seen = true unless TkCOMMENT === tk
+      
+      case tk
+      when TkNL then
+        skip_tkspace true # Skip blanks and newlines
+        tk = get_tk
+        
+        if TkCOMMENT === tk then
+          if non_comment_seen then
+            # Look for RDoc in a comment about to be thrown away
+            parse_comment container, tk, comment unless comment.empty?
+            
+            comment = ''
+            non_comment_seen = false
+          end
+          
+          while TkCOMMENT === tk do
+            comment << tk.text << "\n"
+            tk = get_tk          # this is the newline
+            skip_tkspace(false)  # leading spaces
+            tk = get_tk
+          end
+          
+          unless comment.empty? then
+            look_for_directives_in container, comment
+            
+            if container.done_documenting then
+              container.ongoing_visibility = save_visibility
+            end
+          end
+          
+          keep_comment = true
+        else
+          non_comment_seen = true
+        end
+        
+        unget_tk tk
+        keep_comment = true
+        
+      when TkCLASS then
+        if container.document_children then
+          parse_class container, single, tk, comment
+        else
+          nest += 1
+        end
+        
+      when TkMODULE then
+        if container.document_children then
+          parse_module container, single, tk, comment
+        else
+          nest += 1
+        end
+        
+      when TkDEF then
+        if container.document_self then
+          parse_method container, single, tk, comment
+        else
+          nest += 1
+        end
+        
+      when TkCONSTANT then
+        if container.document_self then
+#          parse_constant container, single, tk, comment
+#	change for rdoc > 2.4.3
+          parse_constant container, tk, comment
+        end
+        
+      when TkALIAS then
+        if container.document_self then
+          parse_alias container, single, tk, comment
+        end
+        
+      when TkYIELD then
+        if current_method.nil? then
+          warn "Warning: yield outside of method" if container.document_self
+        else
+          parse_yield container, single, tk, current_method
+        end
+        
+      # Until and While can have a 'do', which shouldn't increase the nesting.
+      # We can't solve the general case, but we can handle most occurrences by
+      # ignoring a do at the end of a line.
+      when  TkUNTIL, TkWHILE then
+        nest += 1
+        skip_optional_do_after_expression
+        
+      # 'for' is trickier
+      when TkFOR then
+        nest += 1
+        skip_for_variable
+        skip_optional_do_after_expression
+        
+      when TkCASE, TkDO, TkIF, TkUNLESS, TkBEGIN then
+        nest += 1
+        
+      when TkIDENTIFIER then
+        if nest == 1 and current_method.nil? then
+          case tk.name
+          when 'private', 'protected', 'public', 'private_class_method',
+               'public_class_method', 'module_function' then
+            parse_visibility container, single, tk
+            keep_comment = true
+          when 'attr' then
+            parse_attr container, single, tk, comment
+          when /^attr_(reader|writer|accessor)$/ then
+            parse_attr_accessor container, single, tk, comment
+          when 'alias_method' then
+            if container.document_self then
+              parse_alias container, single, tk, comment
+            end
+          when *RAILS_IDENTIFIERS then parse_rails_meta container, single, tk, comment
+          else
+            if container.document_self and comment =~ /\A#\#$/ then
+              parse_meta_method container, single, tk, comment
+            end
+          end
+        end
+        
+        case tk.name
+        when "require" then
+          parse_require container, comment
+        when "include" then
+          parse_include container, comment
+        end
+        
+      when TkEND then
+        nest -= 1
+        if nest == 0 then
+          read_documentation_modifiers container, RDoc::CLASS_MODIFIERS
+          container.ongoing_visibility = save_visibility
+          return
+        end
+        
+      end
+      
+      comment = '' unless keep_comment
+      
+      begin
+        get_tkread
+        skip_tkspace(false)
+      end while peek_tk == TkNL
+    end
+  end
+  
+end

data/lib/rdoc_rails/rdoc/token_stream.rb

@@ -0,0 +1,9 @@
+require 'rdoc/tokenstream'
+module RDoc::TokenStream
+  class TokenStream
+    include RDoc::TokenStream
+    def initialize
+      start_collecting_tokens
+    end
+  end
+end

data/lib/tasks/rdoc_rails.rake

@@ -0,0 +1,19 @@
+require File.expand_path(File.dirname(__FILE__) + '/../rdoc_rails')
+
+Rake::RDocTask.remove_task('doc:app')
+
+namespace :doc do
+  desc "Generate documentation for the application. Set custom template with TEMPLATE=/path/to/rdoc/template.rb Set custom format with FORMAT=format_name"
+  Rake::RDocTask.new('app') { |rdoc|
+    ENV['format'] ||= 'railsfish'
+    rdoc.rdoc_dir = 'doc/app'
+    rdoc.template = ENV['template'] if ENV['template']
+    rdoc.title    = "Rails Application Documentation"
+    rdoc.options << '--line-numbers' << '--inline-source'
+    rdoc.options << '--charset' << 'utf-8'
+    rdoc.options << '--format'  << ENV['format']
+    rdoc.rdoc_files.include('doc/README_FOR_APP')
+    rdoc.rdoc_files.include('app/**/*.rb')
+    rdoc.rdoc_files.include('lib/**/*.rb')
+  }
+end

data/test/app/models/blog.rb

@@ -0,0 +1,4 @@
+class Blog < ActiveRecord::Base
+	belongs_to :user
+	has_many :posts
+end

data/test/app/models/comment.rb

@@ -0,0 +1,12 @@
+class Comment < ActiveRecord::Base
+	#	This will parse incorrectly, ignoring the definition
+	#	of :class_name => "User"
+	belongs_to :commenter, 
+		:class_name => "User",
+		:counter_cache => true
+
+	#	This has no idea who or what commentable is.
+	belongs_to :commentable, 
+		:polymorphic => true,
+		:counter_cache => true
+end

data/test/app/models/post.rb

@@ -0,0 +1,6 @@
+class Post < ActiveRecord::Base
+	has_many :comments,
+		:as => :commentable
+	belongs_to :user, 
+		:counter_cache => true
+end

data/test/app/models/user.rb

@@ -0,0 +1,13 @@
+class User < ActiveRecord::Base
+	has_many :blogs
+	has_many :posts
+	has_many :comments, :as => :commenter
+
+	def self.something_classy
+
+	end
+
+	def something_instancey
+
+	end
+end

data/test/rdoc_rails_test.rb

@@ -0,0 +1,15 @@
+require File.dirname(__FILE__) + '/test_helper'
+require 'fileutils'
+
+class RDocRailsTest < ActiveSupport::TestCase
+
+#	test "should say hello" do
+#		puts 'hello'
+#	end
+
+	test "should do something" do
+		FileUtils.remove_dir("test/rdoc") if File.exists?("test/rdoc")
+		Rake::Task[:rdoc_test].invoke
+	end
+
+end

data/test/tasks/testing.rb

@@ -0,0 +1,9 @@
+require 'rdoc'
+require 'rdoc/rdoc'
+#require 'rake'
+#require 'rake/testtask'
+require 'rake/rdoctask'
+require File.dirname(__FILE__) + '/../../lib/rdoc_rails'
+
+# Load Rails rakefile extensions
+Dir["#{File.dirname(__FILE__)}/*.rake"].each { |ext| load ext }

data/test/test_helper.rb

@@ -0,0 +1,86 @@
+require 'test/unit'
+require 'rubygems'
+require 'active_support'
+require 'active_support/test_case'
+require 'active_record'
+
+require 'tasks/testing'
+$: << File.expand_path(File.dirname(__FILE__) + "/../lib/" )
+require 'rdoc_rails'
+
+$: << File.expand_path(File.dirname(__FILE__) + "/app/models/" )
+%w( user blog post comment ).each{|m| require m }
+
+#ActiveRecord::Base.establish_connection(
+#	:adapter => "sqlite3", 
+#	:database => ":memory:")
+#
+#def setup_db
+#	ActiveRecord::Schema.define(:version => 1) do
+#		create_table :users do |t|
+#		end
+#		create_table :blogs do |t|
+#			t.references :user
+#		end
+#		create_table :posts do |t|
+#			t.references :blog
+#			t.references :user
+#		end
+#		create_table :comments do |t|
+#			t.references :commenter
+#			t.references :commentable, :polymorphic => true
+#		end
+#	end
+#end
+#
+#def teardown_db
+#	ActiveRecord::Base.connection.tables.each do |table|
+#		ActiveRecord::Base.connection.drop_table(table)
+#	end
+#end
+
+
+class ActiveSupport::TestCase
+
+end
+
+
+Rake::Task.class_eval do 
+
+	#	For some reason, a blank prerequisite is added
+	#	which causes
+	#	RuntimeError: Don't know how to build task ''
+	#	so I make sure that they are gone
+	def invoke_prerequisites_with_compressing(
+		task_args, invocation_chain)
+		@prerequisites.delete_if{|a|a.blank?}	# || a =~ /\A\s*\z/ }
+		invoke_prerequisites_without_compressing(
+			task_args, invocation_chain
+		)
+	end
+	alias_method_chain :invoke_prerequisites, :compressing
+
+end
+
+
+RDoc::Generator::Railsfish.class_eval do
+	def generate_class_files
+		debug_msg "Generating class documentation in #@outputdir"
+
+		#	The pathname ends up being incorrect by "../."
+		#	That's all it takes and since there is not apparent
+		#	variable, I just override the method for testing.
+
+		templatefile = Pathname.new("../../lib/rdoc_rails/rdoc/generator/template/railsfish/classpage.rhtml") 
+
+		@classes.each do |klass|
+			debug_msg "  working on %s (%s)" % [ klass.full_name, klass.path ]
+			outfile    = @outputdir + klass.path
+			rel_prefix = @outputdir.relative_path_from( outfile.dirname )
+			svninfo    = self.get_svninfo( klass )
+			debug_msg "  rendering #{outfile}"
+			self.render_template( templatefile, binding(), outfile )
+		end
+	end
+end
+

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification 
+name: jakewendt-rdoc_rails
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors: 
+- Chinasaur
+- George 'Jake' Wendt
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-08 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 2
+        version: "2"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 2
+        version: "2"
+  type: :runtime
+  version_requirements: *id002
+description: longer description of your gem
+email: github@jakewendt.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/jakewendt-rdoc_rails.rb
+- lib/rdoc_rails.rb
+- lib/rdoc_rails/rake.rb
+- lib/rdoc_rails/rdoc/ar_association.rb
+- lib/rdoc_rails/rdoc/context.rb
+- lib/rdoc_rails/rdoc/generator/railsfish.rb
+- lib/rdoc_rails/rdoc/generator/template/railsfish/classpage.rhtml
+- lib/rdoc_rails/rdoc/parser/rails.rb
+- lib/rdoc_rails/rdoc/token_stream.rb
+- lib/tasks/rdoc_rails.rake
+- README.rdoc
+- test/app/models/blog.rb
+- test/app/models/comment.rb
+- test/app/models/post.rb
+- test/app/models/user.rb
+- test/rdoc_rails_test.rb
+- test/tasks/testing.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/jakewendt/rdoc_rails
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: one-line summary of your gem
+test_files: 
+- test/app/models/blog.rb
+- test/app/models/comment.rb
+- test/app/models/post.rb
+- test/app/models/user.rb
+- test/rdoc_rails_test.rb
+- test/tasks/testing.rb
+- test/test_helper.rb