rdoc 2.4.1 → 2.4.2

data/History.txt

@@ -1,3 +1,28 @@
+=== 2.4.2 / 2009-03-25
+
+* 2 Minor Enhancements
+  * Added --pipe for turning RDoc on stdin into HTML
+  * Added rdoc/task.rb containing a replacement for rake/rdoctask.rb.  Use
+    RDoc::Task now instead of Rake::RDocTask.
+
+* 10 Bug Fixes
+  * Writing the ri cache file to the proper directory.  Bug #24459 by Lars
+    Christensen.
+  * Possible fix for Dir::[] and Pathname interaction on 1.9.  Bug #24650 by
+    tiburon.
+  * Fixed scanning constants for if/end, etc. pairs.  Bug #24609 by Ryan
+    Davis.
+  * Fixed private methods in the C parser.  Bug #24599 by Aaron Patterson.
+  * Fixed display of markup on RDoc main page.  Bug #24168 by rhubarb.
+  * Fixed display of \\ character in documentation proceeding words.
+    Bug #22112 by James Gray.  See RDoc for details.
+  * Fixed parsing and display of arg params for some corner cases.  Bug #21113
+    by Csiszár Attila.
+  * Fixed links in Files box.  Patch #24403 by Eric Wong.
+  * Toplevel methods now appear in Object.  Bug #22677 by Ryan Davis.
+  * Added back --promiscuous which didn't do anything you cared about.  Why
+    did you enable it?  Nobody looked at that page!  Oh, it warns, too.
+
 === 2.4.1 / 2009-02-26
 
 * 1 Minor Enhancements

data/Manifest.txt

@@ -92,6 +92,7 @@ lib/rdoc/ri/util.rb
 lib/rdoc/ri/writer.rb
 lib/rdoc/single_class.rb
 lib/rdoc/stats.rb
+lib/rdoc/task.rb
 lib/rdoc/tokenstream.rb
 lib/rdoc/top_level.rb
 test/binary.dat
@@ -119,6 +120,7 @@ test/test_rdoc_ri_driver.rb
 test/test_rdoc_ri_formatter.rb
 test/test_rdoc_ri_html_formatter.rb
 test/test_rdoc_ri_overstrike_formatter.rb
+test/test_rdoc_task.rb
 test/test_rdoc_top_level.rb
 test/xref_data.rb
 test/xref_test_case.rb

data/Rakefile

@@ -14,6 +14,7 @@ Hoe.new "rdoc", RDoc::VERSION do |rdoc|
 
   rdoc.extra_dev_deps << ['minitest', '~> 1.3']
   rdoc.spec_extras['required_rubygems_version'] = '>= 1.3'
+  rdoc.spec_extras['homepage'] = 'http://rdoc.rubyforge.org'
 end
 
 # These tasks expect to have the following directory structure:

data/lib/rdoc.rb

@@ -61,6 +61,7 @@ $DEBUG_RDOC = nil
 # recursively for C and Ruby source files only.
 #
 # == \Options
+#
 # rdoc can be passed a variety of command-line options.  In addition,
 # options can be specified via the +RDOCOPT+ environment variable, which
 # functions similarly to the +RUBYOPT+ environment variable.
@@ -70,28 +71,15 @@ $DEBUG_RDOC = nil
 # will make rdoc default to inline method source code.  Command-line options
 # always will override those in +RDOCOPT+.
 #
-# Run
+# Run:
 # 
-#   % rdoc --help
+#   rdoc --help
 #
 # for full details on rdoc's options.
 #
-# Here are some of the most commonly used options.
-# [-d, --diagram]
-#   Generate diagrams showing modules and
-#   classes. You need dot V1.8.6 or later to
-#   use the --diagram option correctly. Dot is
-#   available from http://graphviz.org
-#
-# [-S, --inline-source]
-#   Show method source code inline, rather than via a popup link.
-#
-# [-T, --template=NAME]
-#   Set the template used when generating output.
-#
 # == Documenting Source Code
 #
-# Comment blocks can be written fairly naturally, either using +#+ on
+# Comment blocks can be written fairly naturally, either using <tt>#</tt> on
 # successive lines of the comment, or by including the comment in
 # a =begin/=end block.  If you use the latter form, the =begin line must be
 # flagged with an RDoc tag:
@@ -150,6 +138,11 @@ $DEBUG_RDOC = nil
 # +:yields:+ is an example of a documentation directive.  These appear
 # immediately after the start of the document element they are modifying.
 #
+# RDoc automatically cross-references words with underscores or camel-case.
+# To suppress cross-references, prefix the word with a \\ character.  To
+# include special characters like "\\n", you'll need to use two \\
+# characters like "\\\\\\n".
+#
 # == \Markup
 #
 # * The markup engine looks for a document's natural left margin.  This is
@@ -216,17 +209,17 @@ $DEBUG_RDOC = nil
 #
 #   Word-based markup uses flag characters around individual words:
 #
-#   [\*word*]  displays word in a *bold* font
-#   [\_word_]  displays word in an _emphasized_ font
-#   [\+word+]  displays word in a +code+ font
+#   [<tt>\*word*</tt>]  displays word in a *bold* font
+#   [<tt>\_word_</tt>]  displays word in an _emphasized_ font
+#   [<tt>\+word+</tt>]  displays word in a +code+ font
 #
 #   General markup affects text between a start delimiter and and end
 #   delimiter.  Not surprisingly, these delimiters look like HTML markup.
 #
-#   [\<b>text...</b>]    displays word in a *bold* font
-#   [\<em>text...</em>]  displays word in an _emphasized_ font
-#   [\<i>text...</i>]    displays word in an <i>italicized</i> font
-#   [\<tt>text...</tt>]  displays word in a +code+ font
+#   [<tt>\<b>text...</b></tt>]    displays word in a *bold* font
+#   [<tt>\<em>text...</em></tt>]  displays word in an _emphasized_ font
+#   [<tt>\<i>text...</i></tt>]    displays word in an <i>italicized</i> font
+#   [<tt>\<tt>text...\</tt></tt>]  displays word in a +code+ font
 #
 #   Unlike conventional Wiki markup, general markup can cross line
 #   boundaries.  You can turn off the interpretation of markup by
@@ -382,7 +375,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = "2.4.1"
+  VERSION = "2.4.2"
 
   ##
   # Name of the dotfile that contains the description of files to be processed

data/lib/rdoc/context.rb

@@ -361,7 +361,7 @@ class RDoc::Context < RDoc::CodeObject
 
   def add_method(method)
     method.visibility = @visibility
-    add_to(@method_list, method)
+    add_to @method_list, method
 
     unmatched_alias_list = @unmatched_alias_lists[method.name]
     if unmatched_alias_list then

data/lib/rdoc/generator/darkfish.rb

@@ -155,7 +155,7 @@ class RDoc::Generator::Darkfish
 
 		FileUtils.cp @template_dir + 'rdoc.css', '.', options
 
-		Dir[@template_dir + "{js,images}/**/*"].each do |path|
+		Dir[(@template_dir + "{js,images}/**/*").to_s].each do |path|
 			next if File.directory? path
 			next if path =~ /#{File::SEPARATOR}\./
 

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

@@ -28,7 +28,7 @@
 				<div class="section-body">
 					<ul>
 					<% klass.in_files.each do |tl| %>
-						<li><a href="<%= rel_prefix %>/<%= h tl.absolute_name %>.html?TB_iframe=true&amp;height=550&amp;width=785"
+						<li><a href="<%= rel_prefix %>/<%= h tl.path %>.html?TB_iframe=true&amp;height=550&amp;width=785"
 							class="thickbox" title="<%= h tl.absolute_name %>"><%= h tl.absolute_name %></a></li>
 					<% end %>
 					</ul>

data/lib/rdoc/markup/attribute_manager.rb

@@ -227,7 +227,7 @@ class RDoc::Markup::AttributeManager
 
     unmask_protected_sequences
 
-    return split_into_flow
+    split_into_flow
   end
 
   ##
@@ -304,7 +304,7 @@ class RDoc::Markup::AttributeManager
     # and reset to all attributes off
     res << change_attribute(current_attr, 0) if current_attr != 0
 
-    return res
+    res
   end
 
 end

data/lib/rdoc/markup/to_html_crossref.rb

@@ -121,7 +121,9 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     ref = @context.find_symbol lookup unless ref
 
-    out = if lookup =~ /^\\/ then
+    out = if lookup == '\\' then
+            lookup
+          elsif lookup =~ /^\\/ then
             $'
           elsif ref and ref.document_self then
             "<a href=\"#{ref.as_href(@from_path)}\">#{name}</a>"

data/lib/rdoc/options.rb

@@ -73,6 +73,11 @@ class RDoc::Options
 
   attr_accessor :op_dir
 
+  ##
+  # Is RDoc in pipe mode?
+
+  attr_accessor :pipe
+
   ##
   # Array of directories to search for files to satisfy an :include:
 
@@ -127,6 +132,7 @@ class RDoc::Options
     @exclude = []
     @generators = RDoc::RDoc::GENERATORS
     @generator = RDoc::Generator::Darkfish
+    @generator_name = nil
     @rdoc_include = []
     @title = nil
     @template = nil
@@ -143,6 +149,7 @@ class RDoc::Options
     @include_line_numbers = false
     @force_update = true
     @verbosity = 1
+    @pipe = false
 
     @webcvs = nil
 
@@ -176,7 +183,7 @@ Usage: #{opt.program_name} [options] [names...]
       EOF
 
       opt.separator nil
-      opt.separator "Options:"
+      opt.separator "Parsing Options:"
       opt.separator nil
 
       opt.on("--all", "-a",
@@ -187,31 +194,6 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--charset=CHARSET", "-c",
-             "Specifies the output HTML character-set.") do |value|
-        @charset = value
-      end
-
-      opt.separator nil
-
-      opt.on("--debug", "-D",
-             "Displays lots on internal stuff.") do |value|
-        $DEBUG_RDOC = value
-      end
-
-      opt.separator nil
-
-      opt.on("--diagram", "-d",
-             "Generate diagrams showing modules and",
-             "classes. You need dot V1.8.6 or later to",
-             "use the --diagram option correctly. Dot is",
-             "available from http://graphviz.org") do |value|
-        check_diagram
-        @diagram = true
-      end
-
-      opt.separator nil
-
       opt.on("--exclude=PATTERN", "-x", Regexp,
              "Do not process files or directories",
              "matching PATTERN.") do |value|
@@ -237,18 +219,6 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--fileboxes", "-F",
-             "Classes are put in boxes which represents",
-             "files, where these classes reside. Classes",
-             "shared between more than one file are",
-             "shown with list of files that are sharing",
-             "them. Silently discarded if --diagram is",
-             "not given.") do |value|
-        @fileboxes = value
-      end
-
-      opt.separator nil
-
       opt.on("--force-update", "-U",
              "Forces rdoc to scan all sources even if",
              "newer than the flag file.") do |value|
@@ -257,6 +227,29 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
+      opt.on("--pipe",
+             "Convert RDoc on stdin to HTML") do
+        @pipe = true
+      end
+
+      opt.separator nil
+
+      opt.on("--threads=THREADS", Integer,
+             "Number of threads to parse with.") do |threads|
+        @threads = threads
+      end
+
+      opt.separator nil
+      opt.separator "Generator Options:"
+      opt.separator nil
+
+      opt.on("--charset=CHARSET", "-c",
+             "Specifies the output HTML character-set.") do |value|
+        @charset = value
+      end
+
+      opt.separator nil
+
       generator_text = @generators.keys.map { |name| "  #{name}" }.sort
 
       opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys,
@@ -267,19 +260,8 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      image_formats = %w[gif png jpg jpeg]
-      opt.on("--image-format=FORMAT", "-I", image_formats,
-             "Sets output image format for diagrams. Can",
-             "be #{image_formats.join ', '}. If this option",
-             "is omitted, png is used. Requires",
-             "diagrams.") do |value|
-        @image_format = value
-      end
-
-      opt.separator nil
-
       opt.on("--include=DIRECTORIES", "-i", Array,
-             "set (or add to) the list of directories to",
+             "Set (or add to) the list of directories to",
              "be searched when satisfying :include:",
              "requests. Can be used more than once.") do |value|
         @rdoc_include.concat value.map { |dir| dir.strip }
@@ -301,29 +283,94 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--merge", "-M",
-             "When creating ri output, merge previously",
-             "processed classes into previously",
-             "documented classes of the same name.") do |value|
-        @merge = value
+      opt.on("--output=DIR", "--op", "-o",
+             "Set the output directory.") do |value|
+        @op_dir = value
       end
 
       opt.separator nil
 
-      opt.on("--output=DIR", "--op", "-o",
-             "Set the output directory.") do |value|
-        @op_dir = value
+      opt.on("--show-hash", "-H",
+             "A name of the form #name in a comment is a",
+             "possible hyperlink to an instance method",
+             "name. When displayed, the '#' is removed",
+             "unless this option is specified.") do |value|
+        @show_hash = value
       end
 
       opt.separator nil
 
-      opt.on("--quiet", "-q",
-             "Don't show progress as we parse.") do |value|
-        @verbosity = 0
+      opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger,
+             "Set the width of tab characters.") do |value|
+        @tab_width = value
+      end
+
+      opt.separator nil
+
+      opt.on("--template=NAME", "-T",
+             "Set the template used when generating",
+             "output.") do |value|
+        @template = value
       end
 
       opt.separator nil
 
+      opt.on("--title=TITLE", "-t",
+             "Set TITLE as the title for HTML output.") do |value|
+        @title = value
+      end
+
+      opt.separator nil
+
+      opt.on("--webcvs=URL", "-W",
+             "Specify a URL for linking to a web frontend",
+             "to CVS. If the URL contains a '\%s', the",
+             "name of the current file will be",
+             "substituted; if the URL doesn't contain a",
+             "'\%s', the filename will be appended to it.") do |value|
+        @webcvs = value
+      end
+
+      opt.separator nil
+      opt.separator "Diagram Options:"
+      opt.separator nil
+
+      image_formats = %w[gif png jpg jpeg]
+      opt.on("--image-format=FORMAT", "-I", image_formats,
+             "Sets output image format for diagrams. Can",
+             "be #{image_formats.join ', '}. If this option",
+             "is omitted, png is used. Requires",
+             "diagrams.") do |value|
+        @image_format = value
+      end
+
+      opt.separator nil
+
+      opt.on("--diagram", "-d",
+             "Generate diagrams showing modules and",
+             "classes. You need dot V1.8.6 or later to",
+             "use the --diagram option correctly. Dot is",
+             "available from http://graphviz.org") do |value|
+        check_diagram
+        @diagram = true
+      end
+
+      opt.separator nil
+
+      opt.on("--fileboxes", "-F",
+             "Classes are put in boxes which represents",
+             "files, where these classes reside. Classes",
+             "shared between more than one file are",
+             "shown with list of files that are sharing",
+             "them. Silently discarded if --diagram is",
+             "not given.") do |value|
+        @fileboxes = value
+      end
+
+      opt.separator nil
+      opt.separator "ri Generator Options:"
+      opt.separator nil
+
       opt.on("--ri", "-r",
              "Generate output for use by `ri`. The files",
              "are stored in the '.rdoc' directory under",
@@ -349,70 +396,45 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--show-hash", "-H",
-             "A name of the form #name in a comment is a",
-             "possible hyperlink to an instance method",
-             "name. When displayed, the '#' is removed",
-             "unless this option is specified.") do |value|
-        @show_hash = value
-      end
-
-      opt.separator nil
-
-      opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger,
-             "Set the width of tab characters.") do |value|
-        @tab_width = value
+      opt.on("--merge", "-M",
+             "When creating ri output, merge previously",
+             "processed classes into previously",
+             "documented classes of the same name.") do |value|
+        @merge = value
       end
 
       opt.separator nil
-
-      opt.on("--template=NAME", "-T",
-             "Set the template used when generating",
-             "output.") do |value|
-        @template = value
-      end
-
+      opt.separator "Generic Options:"
       opt.separator nil
 
-      opt.on("--threads=THREADS", Integer,
-             "Number of threads to parse with.") do |threads|
-        @threads = threads
+      opt.on("--debug", "-D",
+             "Displays lots on internal stuff.") do |value|
+        $DEBUG_RDOC = value
       end
 
-      opt.separator nil
-
-      opt.on("--title=TITLE", "-t",
-             "Set TITLE as the title for HTML output.") do |value|
-        @title = value
+      opt.on("--quiet", "-q",
+             "Don't show progress as we parse.") do |value|
+        @verbosity = 0
       end
 
-      opt.separator nil
-
       opt.on("--verbose", "-v",
              "Display extra progress as we parse.") do |value|
         @verbosity = 2
       end
 
       opt.separator nil
-
-      opt.on("--webcvs=URL", "-W",
-             "Specify a URL for linking to a web frontend",
-             "to CVS. If the URL contains a '\%s', the",
-             "name of the current file will be",
-             "substituted; if the URL doesn't contain a",
-             "'\%s', the filename will be appended to it.") do |value|
-        @webcvs = value
-      end
-
-      opt.separator nil
-
       opt.separator 'Deprecated options - these warn when set'
-
       opt.separator nil
 
       opt.on("--inline-source", "-S") do |value|
         warn "--inline-source will be removed from RDoc on or after August 2009"
       end
+
+      opt.on("--promiscuous", "-p") do |value|
+        warn "--promiscuous will be removed from RDoc on or after August 2009"
+      end
+
+      opt.separator nil
     end
 
     argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']