rdoc 3.10.pre.3 → 3.10

data/History.rdoc

@@ -2,7 +2,8 @@
 
 * Major enhancements
   * RDoc HTML output has been improved:
-    * The search from Володя Колесников's sdoc has been integrated.
+    * The search from Володя Колесников's (Vladimir Kolesnikov) Sdoc has been
+      integrated.
 
       The search index generation is a reusable component through
       RDoc::Generator::JsonIndex
@@ -24,8 +25,21 @@
     overrides the default markup format.
 
     The markup format can be set for rake tasks using RDoc::Task#markup
+  * RDoc can save and load an options file.
+
+    To create an options file that defaults to using TomDoc markup run:
+
+      rdoc --markup tomdoc --write-options
+
+    This will create a .rdoc_options file.  Check it in to your VCS and
+    package it with your gem.  RDoc will automatically load this file and
+    combine it with the user's options.
+
+    Some options are not saved.  See RDoc::Options@Saved+Options for full
+    details.
 
 * Minor enhancements
+  * RDoc autoloads everything.  You only need to require 'rdoc' now.
   * HTML headings now have ids matching their titles.
 
       = Hello!
@@ -39,9 +53,9 @@
     <tt>RDoc::Markup@Links</tt>
 
     See RDoc::Markup@Links for further details.
-  * RDoc now looks for a <tt>markup: parser_name</tt> magic comment to choose
-    alternate documentation formats.  The format comment must be in the first
-    three lines of the file (to allow for a shebang or modeline).
+  * For HTML output RDoc uses +SomeClass.method_name+ and
+    +SomeClass#method_name+ for remote methods and attributes and
+    +::method_name+ and +#method_name+ for local methods.
   * RDoc makes an effort to syntax-highlight ruby code in verbatim sections.
     See RDoc::Markup@Paragraphs+and+Verbatim
   * Added RDoc::TopLevel#text? and RDoc::Parser::Text to indicate a
@@ -58,6 +72,10 @@
   * Moved token stream HTML markup out of RDoc::AnyMethod#markup_code into
     RDoc::TokenStream::to_html
   * "Top" link in section headers is no longer inside the heading element.
+  * RDoc avoids printing some warnings unless run with `rdoc --verbose`.  For
+    Rails issue #1646.
+  * Finishing a paragraph with two or more spaces will result in a line break.
+    This feature is experimental and may be modified or removed.
 
 * Bug fixes
   * Markup defined by RDoc::Markup#add_special inside a <tt><tt></tt> is no
@@ -71,6 +89,19 @@
   * Fixed RDoc::Markup::Parser for CRLF line endings.  Issue #67 by Marvin
     Gülker.
   * Fixed lexing of percent strings like %r{#}.  Issue #68 by eclectic923.
+  * The C parser now understands classes defined with
+    +rb_struct_define_without_accessor+ (like Range).  Pull Request #73 by Dan
+    Bernier
+  * Fixed lexing of <code>a b <<-HEREDOC</code>.  Issue #75 by John Mair.
+  * Added LEGAL.rdoc with references to licenses in other files.  Issue #78 by
+    Dmitry Jemerov.
+  * Block parameters are displayed in Darkfish output again.  Issue #76 by
+    Andrea Singh.
+  * The method parameter coverage report no longer includes parameter default
+    values.  Issue #77 by Jake Goulding.
+  * The module for an include is not looked up until parsed all the files are
+    parsed.  Unless your project includes nonexistent modules this avoids
+    worst-case behavior (<tt>O(n!)</tt>) of RDoc::Include#module.
 
 === 3.9.2 / 2011-08-11
 

data/LEGAL.rdoc

@@ -0,0 +1,27 @@
+# coding: UTF-8
+
+= Legal Notice Information
+
+The files in this distribution are covered by the Ruby license (see LICENSE) except the features mentioned below:
+
+Darkfish::
+  Darkfish was written by Michael Granger and is included under the MIT
+  license.  Darkfish contains images from the Silk Icons set by Mark James.
+
+  See lib/rdoc/generator/darkfish.rb for license information.
+
+  * lib/rdoc/generator/darkfish.rb
+  * lib/rdoc/generator/template/darkfish/*
+  * lib/rdoc/generator/template/darkfish/images
+
+Sdoc::
+  Portions of SDoc by (Володя Колесников) Vladimir Kolesnikov are included
+  under the MIT license as RDoc::Generator::JsonIndex.  See
+  lib/rdoc/generator/json_index.rb for license information.
+
+  * lib/rdoc/generator/json_index.rb
+  * lib/rdoc/generator/template/json_index/*
+  * The +#search_index+ methods on RDoc::CodeObject subclasses were derived
+    from sdoc.
+  * RDoc::ClassModule#document_self_or_methods comes from Sdoc.
+

data/Manifest.txt

@@ -1,6 +1,7 @@
 .autotest
 .document
 History.rdoc
+LEGAL.rdoc
 LICENSE.rdoc
 Manifest.txt
 README.rdoc

data/Rakefile

@@ -2,6 +2,8 @@ $:.unshift File.expand_path 'lib'
 require 'rdoc'
 require 'hoe'
 
+ENV['BENCHMARK'] = 'yes'
+
 task :docs    => :generate
 task :test    => :generate
 
@@ -41,6 +43,7 @@ Depending on your version of ruby, you may need to install ruby rdoc/ri data:
   self.extra_rdoc_files += %w[
     History.rdoc
     LICENSE.rdoc
+    LEGAL.rdoc
     README.rdoc
     RI.rdoc
     TODO.rdoc
@@ -128,3 +131,4 @@ task :diff_rubinius do
   sh "diff #{diff_options} test #{rubinius_dir}/test/rdoc; true"
 end
 
+

data/TODO.rdoc

@@ -11,11 +11,15 @@ Some file contains some things that might happen in RDoc, or might not
 * Add direct accessor to RDoc::Options to RDoc::Task
 * Remove Public in HTML output if there are only public methods
 * Method markup support for rd documentation
+* Improve SIGINFO handling
+* Global variable support
+* Page support for ri
 
 === 4
 
 API changes to RDoc
 
+* Remove global state
 * Remove RDoc::RDocError
 * RDoc::TopLevel#add_method should automatically create the appropriate method
   class rather than requiring one be passed in.

data/lib/gauntlet_rdoc.rb

@@ -1,3 +1,5 @@
+require 'rubygems'
+Gem.load_yaml
 require 'rdoc'
 require 'gauntlet'
 require 'fileutils'
@@ -7,19 +9,33 @@ require 'fileutils'
 
 class RDoc::Gauntlet < Gauntlet
 
+  def initialize # :nodoc:
+    super
+
+    @args = nil
+    @type = nil
+  end
+
   ##
   # Runs an RDoc generator for gem +name+
 
   def run name
     return if self.data.key? name
 
-    dir = File.expand_path "~/.gauntlet/data/rdoc/#{name}"
+    dir = File.expand_path "~/.gauntlet/data/#{@type}/#{name}"
     FileUtils.rm_rf dir if File.exist? dir
 
     yaml = File.read 'gemspec'
-    spec = Gem::Specification.from_yaml yaml
+    begin
+      spec = Gem::Specification.from_yaml yaml
+    rescue Psych::SyntaxError
+      puts "bad spec #{name}"
+      self.data[name] = false
+      return
+    end
 
-    args = %W[--ri --op #{dir}]
+    args = @args.dup
+    args << '--op' << dir
     args.push(*spec.rdoc_options)
     args << spec.require_paths
     args << spec.extra_rdoc_files
@@ -46,7 +62,23 @@ class RDoc::Gauntlet < Gauntlet
     puts
   end
 
+  ##
+  # Runs the gauntlet with the given +type+ (rdoc or ri) and +filter+ for
+  # which gems to run
+
+  def run_the_gauntlet type = 'rdoc', filter = nil
+    @type = type || 'rdoc'
+    @args = type == 'rdoc' ? [] : %w[--ri]
+    @data_file = "#{DATADIR}/#{@type}-data.yml"
+
+    super filter
+  end
+
 end
 
-RDoc::Gauntlet.new.run_the_gauntlet if $0 == __FILE__
+type = ARGV.shift
+filter = ARGV.shift
+filter = /#{filter}/ if filter
+
+RDoc::Gauntlet.new.run_the_gauntlet type, filter
 

data/lib/rdoc.rb

@@ -27,13 +27,15 @@ $DEBUG_RDOC = nil
 # * If you want to use RDoc to create documentation for your Ruby source files,
 #   see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line
 #   usage.
+# * If you want to store rdoc configuration in your gem see
+#   RDoc::Options@Saved+Options
 # * If you want to write documentation for Ruby files see RDoc::Parser::Ruby
 # * If you want to write documentation for extensions written in C see
 #   RDoc::Parser::C
 # * If you want to generate documentation using <tt>rake</tt> see RDoc::Task.
 # * If you want to drive RDoc programmatically, see RDoc::RDoc.
-# * If you want to use the library to format text blocks into HTML, look at
-#   RDoc::Markup.
+# * If you want to use the library to format text blocks into HTML or other
+#   formats, look at RDoc::Markup.
 # * If you want to make an RDoc plugin such as a generator or directive
 #   handler see RDoc::RDoc.
 # * If you want to write your own output generator see RDoc::Generator.
@@ -143,6 +145,23 @@ module RDoc
   METHOD_MODIFIERS = GENERAL_MODIFIERS +
     %w[arg args yield yields notnew not-new not_new doc]
 
+  ##
+  # Loads the best available YAML library.
+
+  def self.load_yaml
+    begin
+      gem 'psych'
+    rescue Gem::LoadError
+    end
+
+    begin
+      require 'psych'
+    rescue ::LoadError
+    ensure
+      require 'yaml'
+    end
+  end
+
   autoload :RDoc,           'rdoc/rdoc'
 
   autoload :TestCase,       'rdoc/test_case'

data/lib/rdoc/any_method.rb

@@ -166,7 +166,9 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       return []
     end
 
-    params.gsub(/\s+/, '').split ','
+    params = params.gsub(/\s+/, '').split ','
+
+    params.map { |param| param.sub(/=.*/, '') }
   end
 
   ##
@@ -178,10 +180,12 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       params = @call_seq.split("\n").last
       params = params.sub(/[^( ]+/, '')
       params = params.sub(/(\|[^|]+\|)\s*\.\.\.\s*(end|\})/, '\1 \2')
-    else
+    elsif @params then
       params = @params.gsub(/\s*\#.*/, '')
       params = params.tr("\n", " ").squeeze(" ")
       params = "(#{params})" unless params[0] == ?(
+    else
+      params = ''
     end
 
     if @block_params then

data/lib/rdoc/class_module.rb

@@ -374,6 +374,8 @@ class RDoc::ClassModule < RDoc::Context
       end
     end
 
+    @includes.uniq! # clean up
+
     merge_collections method_list, cm.method_list, other_files do |add, meth|
       if add then
         add_method meth
@@ -609,6 +611,8 @@ class RDoc::ClassModule < RDoc::Context
       mod = include.module
       !(String === mod) && RDoc::TopLevel.all_modules_hash[mod.full_name].nil?
     end
+
+    includes.uniq!
   end
 
 end

data/lib/rdoc/context.rb

@@ -398,8 +398,7 @@ class RDoc::Context < RDoc::CodeObject
   # Adds included module +include+ which should be an RDoc::Include
 
   def add_include include
-    add_to @includes, include unless
-      @includes.map { |i| i.full_name }.include? include.full_name
+    add_to @includes, include
 
     include
   end

data/lib/rdoc/generator/template/darkfish/class.rhtml

@@ -104,7 +104,9 @@
         <% if method.call_seq then %>
         <%   method.call_seq.strip.split("\n").each_with_index do |call_seq, i| %>
         <div class="method-heading">
-          <span class="method-callseq"><%= h call_seq.strip.gsub(/->/, '&rarr;').gsub( /^\w+\./m, '') %></span>
+          <span class="method-callseq">
+            <%= h(call_seq.strip.gsub( /^\w+\./m, '')).gsub(/[-=]&gt;/, '&rarr;') %>
+          </span>
           <% if i == 0 then %>
           <span class="method-click-advice">click to toggle source</span>
           <% end %>
@@ -113,7 +115,7 @@
         <% else %>
         <div class="method-heading">
           <span class="method-name"><%= h method.name %></span><span
-            class="method-args"><%= method.params %></span>
+            class="method-args"><%= method.param_seq %></span>
           <span class="method-click-advice">click to toggle source</span>
         </div>
         <% end %>

data/lib/rdoc/include.rb

@@ -15,7 +15,7 @@ class RDoc::Include < RDoc::CodeObject
     super()
     @name = name
     self.comment = comment
-    @module = nil   # cache for module if found
+    @module = nil # cache for module if found
   end
 
   ##
@@ -28,10 +28,11 @@ class RDoc::Include < RDoc::CodeObject
   end
 
   def == other # :nodoc:
-    self.class == other.class and
-      self.name == other.name
+    self.class === other and @name == other.name
   end
 
+  alias eql? ==
+
   ##
   # Full name based on #module
 
@@ -40,6 +41,10 @@ class RDoc::Include < RDoc::CodeObject
     RDoc::ClassModule === m ? m.full_name : @name
   end
 
+  def hash # :nodoc:
+    [@name, self.module].hash
+  end
+
   def inspect # :nodoc:
     "#<%s:0x%x %s.include %s>" % [
       self.class,
@@ -57,6 +62,13 @@ class RDoc::Include < RDoc::CodeObject
   # - if not found, look into the children of included modules,
   #   in reverse inclusion order;
   # - if still not found, go up the hierarchy of names.
+  #
+  # This method has <code>O(n!)</code> behavior when the module calling
+  # include is referencing nonexistent modules.  Avoid calling #module until
+  # after all the files are parsed.  This behavior is due to ruby's constant
+  # lookup behavior.
+  #
+  # As of the beginning of October, 2011, no gem includes nonexistent modules.
 
   def module
     return @module if @module
@@ -79,12 +91,12 @@ class RDoc::Include < RDoc::CodeObject
     end
 
     # go up the hierarchy of names
-    p = parent.parent
-    while p
-      full_name = p.child_name(@name)
+    up = parent.parent
+    while up
+      full_name = up.child_name(@name)
       @module = RDoc::TopLevel.modules_hash[full_name]
       return @module if @module
-      p = p.parent
+      up = up.parent
     end
 
     @name

data/lib/rdoc/markup/parser.rb

@@ -203,6 +203,11 @@ class RDoc::Markup::Parser
 
       if type == :TEXT && column == margin then
         paragraph << data
+
+        if peek_token[0] == :BREAK then
+          break
+        end
+
         skip :NEWLINE
       else
         unget
@@ -268,7 +273,7 @@ class RDoc::Markup::Parser
         peek_column ||= column + width
         indent = peek_column - column - width
         line << ' ' * indent
-      when :TEXT then
+      when :BREAK, :TEXT then
         line << data
       else # *LIST_TOKENS
         list_marker = case type
@@ -322,7 +327,12 @@ class RDoc::Markup::Parser
     until @tokens.empty? do
       type, data, column, = get
 
-      if type == :NEWLINE then
+      case type
+      when :BREAK then
+        parent << RDoc::Markup::BlankLine.new
+        skip :NEWLINE, false
+        next
+      when :NEWLINE then
         # trailing newlines are skipped below, so this is a blank line
         parent << RDoc::Markup::BlankLine.new
         skip :NEWLINE, false
@@ -458,8 +468,15 @@ class RDoc::Markup::Parser
                  when s.scan(/(.*?)::( +|\r?$)/) then
                    [:NOTE, s[1], *token_pos(pos)]
                  # anything else: :TEXT
-                 else s.scan(/.*/)
-                   [:TEXT, s.matched.sub(/\r$/, ''), *token_pos(pos)]
+                 else s.scan(/(.*?)(  )?\r?$/)
+                   token = [:TEXT, s[1], *token_pos(pos)]
+
+                   if s[2] then
+                     @tokens << token
+                     [:BREAK, s[2], *token_pos(pos + s[1].length)]
+                   else
+                     token
+                   end
                  end
     end