* lib/rdoc: Update to RDoc 3.9. Fixed `ri []`, stopdoc creating an

object reference, nodoc for class aliases, verbatim === lines.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32767 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Sun Jul 31 09:18:28 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/rdoc:  Update to RDoc 3.9.  Fixed `ri []`, stopdoc creating an
+	  object reference, nodoc for class aliases, verbatim === lines.
+
 Sun Jul 31 01:29:08 2011  NARUSE, Yui  <naruse@ruby-lang.org>
 
 	* io.c (rb_io_each_byte): remove unused variable e.

bin/rdoc

@@ -8,6 +8,13 @@
 #
 #  $Revision$
 
+begin
+  gem 'rdoc'
+rescue NameError => e # --disable-gems
+  raise unless e.name == :gem
+rescue Gem::LoadError
+end
+
 require 'rdoc/rdoc'
 
 begin

bin/ri

@@ -1,5 +1,12 @@
 #!/usr/bin/env ruby
 
+begin
+  gem 'rdoc'
+rescue NameError => e # --disable-gems
+  raise unless e.name == :gem
+rescue Gem::LoadError
+end
+
 require 'rdoc/ri/driver'
 
 RDoc::RI::Driver.run ARGV

lib/rdoc.rb

@@ -104,7 +104,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '3.8'
+  VERSION = '3.9'
 
   ##
   # Method visibilities

lib/rdoc/class_module.rb

@@ -222,6 +222,9 @@ class RDoc::ClassModule < RDoc::Context
                    end
   end
 
+  ##
+  # TODO: filter included items by #display?
+
   def marshal_dump # :nodoc:
     attrs = attributes.sort.map do |attr|
       [ attr.name, attr.rw,

lib/rdoc/code_object.rb

@@ -114,6 +114,7 @@ class RDoc::CodeObject
     @done_documenting    = false
     @force_documentation = false
     @received_nodoc      = false
+    @ignored             = false
   end
 
   ##
@@ -139,6 +140,13 @@ class RDoc::CodeObject
                end
   end
 
+  ##
+  # Should this CodeObject be shown in documentation?
+
+  def display?
+    @document_self and not @ignored
+  end
+
   ##
   # Enables or disables documentation of this CodeObject's children unless it
   # has been turned off by :enddoc:
@@ -195,6 +203,11 @@ class RDoc::CodeObject
     self
   end
 
+  ##
+  # File name where this CodeObject was found.
+  #
+  # See also RDoc::Context#in_files
+
   def file_name
     return unless @file
 
@@ -220,6 +233,34 @@ class RDoc::CodeObject
     @full_name = full_name
   end
 
+  ##
+  # Use this to ignore a CodeObject and all its children until found again
+  # (#record_location is called).  An ignored item will not be shown in
+  # documentation.
+  #
+  # See github issue #55
+  #
+  # The ignored status is temporary in order to allow implementation details
+  # to be hidden.  At the end of processing a file RDoc allows all classes
+  # and modules to add new documentation to previously created classes.
+  #
+  # If a class was ignored (via stopdoc) then reopened later with additional
+  # documentation it should be shown.  If a class was ignored and never
+  # reopened it should not be shown.  The ignore flag allows this to occur.
+
+  def ignore
+    @ignored = true
+
+    stop_doc
+  end
+
+  ##
+  # Has this class been ignored?
+
+  def ignored?
+    @ignored
+  end
+
   ##
   # File name of our parent
 
@@ -238,6 +279,7 @@ class RDoc::CodeObject
   # Records the RDoc::TopLevel (file) where this code object was defined
 
   def record_location top_level
+    @ignored = false
     @file = top_level
   end
 
@@ -250,6 +292,7 @@ class RDoc::CodeObject
 
     @document_self = true
     @document_children = true
+    @ignored = false
   end
 
   ##

lib/rdoc/context.rb

@@ -423,6 +423,7 @@ class RDoc::Context < RDoc::CodeObject
     if klass then
       # if TopLevel, it may not be registered in the classes:
       enclosing.classes_hash[name] = klass
+
       # update the superclass if needed
       if superclass then
         existing = klass.superclass
@@ -623,8 +624,10 @@ class RDoc::Context < RDoc::CodeObject
 
   ##
   # Is there any content?
-  # This means any of: comment, aliases, methods, attributes,
-  # external aliases, require, constant.
+  #
+  # This means any of: comment, aliases, methods, attributes, external
+  # aliases, require, constant.
+  #
   # Includes are also checked unless <tt>includes == false</tt>.
 
   def any_content(includes = true)

lib/rdoc/cross_reference.rb

@@ -0,0 +1,173 @@
+##
+# RDoc::CrossReference is a reusable way to create cross references for names.
+
+class RDoc::CrossReference
+
+  ##
+  # Regular expression to match class references
+  #
+  # 1. There can be a '\\' in front of text to suppress the cross-reference
+  # 2. There can be a '::' in front of class names to reference from the
+  #    top-level namespace.
+  # 3. The method can be followed by parenthesis (not recommended)
+
+  CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
+
+  ##
+  # Regular expression to match method references.
+  #
+  # See CLASS_REGEXP_STR
+
+  METHOD_REGEXP_STR = '([a-z]\w*[!?=]?)(?:\([\w.+*/=<>-]*\))?'
+
+  ##
+  # Regular expressions matching text that should potentially have
+  # cross-reference links generated are passed to add_special.  Note that
+  # these expressions are meant to pick up text for which cross-references
+  # have been suppressed, since the suppression characters are removed by the
+  # code that is triggered.
+
+  CROSSREF_REGEXP = /(
+                      # A::B::C.meth
+                      #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
+
+                      # Stand-alone method (preceded by a #)
+                      | \\?\##{METHOD_REGEXP_STR}
+
+                      # Stand-alone method (preceded by ::)
+                      | ::#{METHOD_REGEXP_STR}
+
+                      # A::B::C
+                      # The stuff after CLASS_REGEXP_STR is a
+                      # nasty hack.  CLASS_REGEXP_STR unfortunately matches
+                      # words like dog and cat (these are legal "class"
+                      # names in Fortran 95).  When a word is flagged as a
+                      # potential cross-reference, limitations in the markup
+                      # engine suppress other processing, such as typesetting.
+                      # This is particularly noticeable for contractions.
+                      # In order that words like "can't" not
+                      # be flagged as potential cross-references, only
+                      # flag potential class cross-references if the character
+                      # after the cross-reference is a space, sentence
+                      # punctuation, tag start character, or attribute
+                      # marker.
+                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
+
+                      # Things that look like filenames
+                      # The key thing is that there must be at least
+                      # one special character (period, slash, or
+                      # underscore).
+                      | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
+
+                      # Things that have markup suppressed
+                      # Don't process things like '\<' in \<tt>, though.
+                      # TODO: including < is a hack, not very satisfying.
+                      | \\[^\s<]
+                      )/x
+
+  ##
+  # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.
+
+  ALL_CROSSREF_REGEXP = /(
+                      # A::B::C.meth
+                      #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
+
+                      # Stand-alone method
+                      | \\?#{METHOD_REGEXP_STR}
+
+                      # A::B::C
+                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
+
+                      # Things that look like filenames
+                      | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
+
+                      # Things that have markup suppressed
+                      | \\[^\s<]
+                      )/x
+
+  attr_accessor :seen
+
+  ##
+  # Allows cross-references to be created based on the given +context+
+  # (RDoc::Context).
+
+  def initialize context
+    @context = context
+
+    @seen = {}
+  end
+
+  ##
+  # Returns a reference to +name+.
+  #
+  # If the reference is found and +name+ is not documented +text+ will be
+  # returned.  If +name+ is escaped +name+ is returned.  If +name+ is not
+  # found +text+ is returned.
+
+  def resolve name, text
+    return @seen[name] if @seen.include? name
+
+    # Find class, module, or method in class or module.
+    #
+    # Do not, however, use an if/elsif/else chain to do so.  Instead, test
+    # each possible pattern until one matches.  The reason for this is that a
+    # string like "YAML.txt" could be the txt() class method of class YAML (in
+    # which case it would match the first pattern, which splits the string
+    # into container and method components and looks up both) or a filename
+    # (in which case it would match the last pattern, which just checks
+    # whether the string as a whole is a known symbol).
+
+    if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+      type = $2
+      type = '' if type == '.'  # will find either #method or ::method
+      method = "#{type}#{$3}"
+      container = @context.find_symbol_module($1)
+    elsif /^([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
+      type = $1
+      type = '' if type == '.'
+      method = "#{type}#{$2}"
+      container = @context
+    else
+      container = nil
+    end
+
+    if container then
+      ref = container.find_local_symbol method
+
+      unless ref || RDoc::TopLevel === container then
+        ref = container.find_ancestor_local_symbol method
+      end
+    end
+
+    ref = case name
+          when /^\\(#{CLASS_REGEXP_STR})$/o then
+            ref = @context.find_symbol $1
+          else
+            ref = @context.find_symbol name
+          end unless ref
+
+    ref = nil if RDoc::Alias === ref # external alias: can't link to it
+
+    out = if name == '\\' then
+            name
+          elsif name =~ /^\\/ then
+            # we remove the \ only in front of what we know:
+            # other backslashes are treated later, only outside of <tt>
+            ref ? $' : name
+          elsif ref then
+            if ref.display? then
+              ref
+            else
+              text
+            end
+          else
+            text
+          end
+
+    @seen[name] = out
+
+    out
+  end
+
+end
+

lib/rdoc/generator/darkfish.rb

@@ -192,7 +192,7 @@ class RDoc::Generator::Darkfish
       top_level = klass.full_name.gsub( /::.*/, '' )
       [nscounts[top_level] * -1, klass.full_name]
     end.select do |klass|
-      klass.document_self
+      klass.display?
     end
   end
 

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

@@ -176,6 +176,8 @@
     </div><!-- description -->
 
     <% klass.each_section do |section, constants, attributes| %>
+    <% constants = constants.select { |const| const.display? } %>
+    <% attributes = attributes.select { |attr| attr.display? } %>
     <div id="<%= section.aref %>" class="documentation-section">
       <% if section.title then %>
       <h2 class="section-header">

lib/rdoc/markup.rb

@@ -269,40 +269,43 @@ require 'rdoc'
 # preceding the first character with a backslash (see <i>Escaping
 # Text Markup</i>, below).
 #
-# === Hyperlinks
+# === Links
 #
-# Hyperlinks to the web starting with +http:+, +mailto:+, +ftp:+ or +www.+
+# Links to starting with +http:+, +https:+, +mailto:+, +ftp:+ or +www.+
 # are recognized.  An HTTP url that references an external image file is
-# converted into an inline <img...>.  Hyperlinks starting with +link:+ are
-# assumed to refer to local files whose path is relative to the <tt>--op</tt>
-# directory.
+# converted into an inline image element.
 #
-# Hyperlinks can also be of the form _label_[_url_], in which
-# case _label_ is used in the displayed text, and _url_ is
-# used as the target.  If _label_ contains multiple words,
-# put it in braces: {<em>multi word label</em>}[url].
+# Links starting with <tt>rdoc-ref:</tt> will link to the referenced class,
+# module, method, file, etc.  If the referenced item is not documented the
+# text will be and no link will be generated.
 #
-# Example hyperlinks:
+# Links starting with +link:+ refer to local files whose path is relative to
+# the <tt>--op</tt> directory.
 #
-#   link:RDoc.html
-#   http://rdoc.rubyforge.org
+# Links can also be of the form <tt>label[url]</tt>, in which case +label+ is
+# used in the displayed text, and +url+ is used as the target.  If +label+
+# contains multiple words, put it in braces: <tt>{multi word label}[url]<tt>.
+#
+# Example links:
+#
+#   https://github.com/rdoc/rdoc
 #   mailto:user@example.com
 #   {RDoc Documentation}[http://rdoc.rubyforge.org]
-#   {RDoc Markup}[link:RDoc/Markup.html]
+#   {RDoc Markup}[rdoc-ref:RDoc::Markup]
 #
 # === Escaping Text Markup
 #
 # Text markup can be escaped with a backslash, as in \<tt>, which was obtained
-# with "<tt>\\<tt></tt>". Except in verbatim sections and between \<tt> tags,
-# to produce a backslash, you have to double it unless it is followed by a
+# with <tt>\\<tt></tt>.  Except in verbatim sections and between \<tt> tags,
+# to produce a backslash you have to double it unless it is followed by a
 # space, tab or newline. Otherwise, the HTML formatter will discard it, as it
-# is used to escape potential hyperlinks:
+# is used to escape potential links:
 #
 #   * The \ must be doubled if not followed by white space: \\.
 #   * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
 #   * This is a link to {ruby-lang}[www.ruby-lang.org].
 #   * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org].
-#   * This will not be hyperlinked to \RDoc::RDoc#document
+#   * This will not be linked to \RDoc::RDoc#document
 #
 # generates:
 #
@@ -310,16 +313,16 @@ require 'rdoc'
 # * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
 # * This is a link to {ruby-lang}[www.ruby-lang.org]
 # * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org]
-# * This will not be hyperlinked to \RDoc::RDoc#document
+# * This will not be linked to \RDoc::RDoc#document
 #
-# Inside \<tt> tags, more precisely, leading backslashes are removed
-# only if followed by a markup character (<tt><*_+</tt>), a backslash,
-# or a known hyperlink reference (a known class or method). So in the
-# example above, the backslash of <tt>\S</tt> would be removed
-# if there was a class or module named +S+ in the current context.
+# Inside \<tt> tags, more precisely, leading backslashes are removed only if
+# followed by a markup character (<tt><*_+</tt>), a backslash, or a known link
+# reference (a known class or method). So in the example above, the backslash
+# of <tt>\S</tt> would be removed if there was a class or module named +S+ in
+# the current context.
 #
-# This behavior is inherited from RDoc version 1, and has been kept
-# for compatibility with existing RDoc documentation.
+# This behavior is inherited from RDoc version 1, and has been kept for
+# compatibility with existing RDoc documentation.
 #
 # === Conversion of characters
 #
@@ -378,11 +381,10 @@ require 'rdoc'
 #     # ...
 #   end
 #
-# Names of classes, files, and any method names containing an
-# underscore or preceded by a hash character are automatically hyperlinked
-# from comment text to their description. This hyperlinking works inside
-# the current class or module, and with ancestor methods (in included modules
-# or in the superclass).
+# Names of classes, files, and any method names containing an underscore or
+# preceded by a hash character are automatically linked from comment text to
+# their description. This linking works inside the current class or module,
+# and with ancestor methods (in included modules or in the superclass).
 #
 # Method parameter lists are extracted and displayed with the method
 # description.  If a method calls +yield+, then the parameters passed to yield

lib/rdoc/markup/document.rb

@@ -71,9 +71,7 @@ class RDoc::Markup::Document
   # Does this document have no parts?
 
   def empty?
-    @parts.empty? or
-      (@parts.length == 1 and RDoc::Markup::Document === @parts.first and
-       @parts.first.empty?)
+    @parts.empty? or (@parts.length == 1 and merged? and @parts.first.empty?)
   end
 
   ##
@@ -85,6 +83,11 @@ class RDoc::Markup::Document
   # The information in +other+ is preferred over the receiver
 
   def merge other
+    if empty? then
+      @parts = other.parts
+      return self
+    end
+
     other.parts.each do |other_part|
       self.parts.delete_if do |self_part|
         self_part.file and self_part.file == other_part.file
@@ -96,6 +99,13 @@ class RDoc::Markup::Document
     self
   end
 
+  ##
+  # Does this Document contain other Documents?
+
+  def merged?
+    RDoc::Markup::Document === @parts.first
+  end
+
   def pretty_print q # :nodoc:
     start = @file ? "[doc (#{@file}): " : '[doc: '
 

lib/rdoc/markup/formatter.rb

@@ -4,6 +4,10 @@ require 'rdoc/markup'
 # Base class for RDoc markup formatters
 #
 # Formatters use a visitor pattern to convert content into output.
+#
+# If you'd like to write your own Formatter use
+# RDoc::Markup::FormatterTestCase.  If you're writing a text-output formatter
+# use RDoc::Markup::TextFormatterTestCase which provides extra test cases.
 
 class RDoc::Markup::Formatter
 

lib/rdoc/markup/parser.rb

@@ -405,13 +405,19 @@ class RDoc::Markup::Parser
                    @line += 1
                    token
                  # === text => :HEADER then :TEXT
-                 when s.scan(/(=+)\s*/) then
+                 when s.scan(/(=+)(\s*)/) then
                    level = s[1].length
-                   level = 6 if level > 6
-                   @tokens << [:HEADER, level, *token_pos(pos)]
-                   pos = s.pos
-                   s.scan(/.*/)
-                   [:TEXT, s.matched.sub(/\r$/, ''), *token_pos(pos)]
+                   header = [:HEADER, level, *token_pos(pos)]
+
+                   if s[2] =~ /^\r?\n/ then
+                     s.pos -= s[2].length
+                     header
+                   else
+                     pos = s.pos
+                     s.scan(/.*/)
+                     @tokens << header
+                     [:TEXT, s.matched.sub(/\r$/, ''), *token_pos(pos)]
+                   end
                  # --- (at least 3) and nothing else on the line => :RULE
                  when s.scan(/(-{3,}) *$/) then
                    [:RULE, s[1].length - 2, *token_pos(pos)]

lib/rdoc/markup/pre_process.rb

@@ -13,6 +13,8 @@ require 'rdoc/encoding'
 
 class RDoc::Markup::PreProcess
 
+  attr_accessor :options
+
   @registered = {}
 
   ##
@@ -38,6 +40,7 @@ class RDoc::Markup::PreProcess
   def initialize(input_file_name, include_path)
     @input_file_name = input_file_name
     @include_path = include_path
+    @options = nil
   end
 
   ##
@@ -54,56 +57,122 @@ class RDoc::Markup::PreProcess
   # If +code_object+ is given and the param is set as metadata on the
   # +code_object+.  See RDoc::CodeObject#metadata
 
-  def handle text, code_object = nil
+  def handle text, code_object = nil, &block
+    encoding = if defined?(Encoding) then text.encoding else nil end
     # regexp helper (square brackets for optional)
     # $1      $2  $3        $4      $5
     # [prefix][\]:directive:[spaces][param]newline
-    text.gsub!(/^([ \t]*#?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do
+    text.gsub!(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do
       # skip something like ':toto::'
       next $& if $4.empty? and $5 and $5[0, 1] == ':'
 
       # skip if escaped
       next "#$1:#$3:#$4#$5\n" unless $2.empty?
 
-      prefix    = $1
-      directive = $3.downcase
-      param     = $5
-
-      case directive
-      when 'include' then
-        filename = param.split[0]
-        encoding = if defined?(Encoding) then text.encoding else nil end
-        include_file filename, prefix, encoding
-      when 'category' then
-        if RDoc::Context === code_object then
-          section = code_object.add_section param, ''
-          code_object.temporary_section = section
-        end
-
-        '' # ignore category if we're not on an RDoc::Context
-      else
-        result = yield directive, param if block_given?
-
-        case result
-        when nil then
-          code_object.metadata[directive] = param if code_object
-          if RDoc::Markup::PreProcess.registered.include? directive then
-            handler = RDoc::Markup::PreProcess.registered[directive]
-            result = handler.call directive, param if handler
-          else
-            result = "#{prefix}:#{directive}: #{param}\n"
-          end
-        when false then
-          result = "#{prefix}:#{directive}: #{param}\n"
-        end
-
-        result
-      end
+      handle_directive $1, $3, $5, code_object, encoding, &block
     end
 
     text
   end
 
+  #--
+  # When 1.8.7 support is ditched prefix can be defaulted to ''
+
+  def handle_directive prefix, directive, param, code_object = nil,
+                       encoding = nil
+    blankline = "#{prefix.strip}\n"
+    directive = directive.downcase
+
+    case directive
+    when 'arg', 'args' then
+      return blankline unless code_object
+
+      code_object.params = param
+
+      blankline
+    when 'category' then
+      if RDoc::Context === code_object then
+        section = code_object.add_section param, ''
+        code_object.temporary_section = section
+      end
+
+      blankline # ignore category if we're not on an RDoc::Context
+    when 'doc' then
+      return blankline unless code_object
+      code_object.document_self = true
+      code_object.force_documentation = true
+
+      blankline
+    when 'enddoc' then
+      return blankline unless code_object
+      code_object.done_documenting = true
+
+      blankline
+    when 'include' then
+      filename = param.split.first
+      include_file filename, prefix, encoding
+    when 'main' then
+      @options.main_page = param if @options.respond_to? :main_page
+
+      blankline
+    when 'nodoc' then
+      return blankline unless code_object
+      code_object.document_self = nil # notify nodoc
+      code_object.document_children = param !~ /all/i
+
+      blankline
+    when 'notnew', 'not_new', 'not-new' then
+      return blankline unless RDoc::AnyMethod === code_object
+
+      code_object.dont_rename_initialize = true
+
+      blankline
+    when 'startdoc' then
+      return blankline unless code_object
+
+      code_object.start_doc
+      code_object.force_documentation = true
+
+      blankline
+    when 'stopdoc' then
+      return blankline unless code_object
+
+      code_object.stop_doc
+
+      blankline
+    when 'title' then
+      @options.default_title = param if @options.respond_to? :default_title=
+
+      blankline
+    when 'yield', 'yields' then
+      return blankline unless code_object
+      # remove parameter &block
+      code_object.params.sub!(/,?\s*&\w+/, '') if code_object.params
+
+      code_object.block_params = param
+
+      blankline
+    else
+      result = yield directive, param if block_given?
+
+      case result
+      when nil then
+        code_object.metadata[directive] = param if code_object
+
+        if RDoc::Markup::PreProcess.registered.include? directive then
+          handler = RDoc::Markup::PreProcess.registered[directive]
+          result = handler.call directive, param if handler
+        else
+          result = "#{prefix}:#{directive}: #{param}\n"
+        end
+      when false then
+        result = "#{prefix}:#{directive}: #{param}\n"
+      end
+
+      result
+    end
+  end
+
   ##
   # Handles the <tt>:include: _filename_</tt> directive.
   #

lib/rdoc/markup/to_html.rb

@@ -70,7 +70,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     @list = nil
     @from_path = ''
 
-    # external hyperlinks
+    # external links
     @markup.add_special(/((link:|https?:|mailto:|ftp:|www\.)\S+\w)/, :HYPERLINK)
 
     # and links of the form  <text>[<url>]
@@ -84,7 +84,7 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   # These methods handle special markup added by RDoc::Markup#add_special.
 
   ##
-  # +special+ is a potential hyperlink.  The following schemes are handled:
+  # +special+ is a potential link.  The following schemes are handled:
   #
   # <tt>mailto:</tt>::
   #   Inserted as-is.
@@ -97,12 +97,13 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
 
   def handle_special_HYPERLINK(special)
     url = special.text
+
     gen_url url, url
   end
 
   ##
-  # This +special+ is a hyperlink where the label is different from the URL
-  # label[url] or {long label}[url]
+  # This +special+ is a link where the label is different from the URL
+  # <tt>label[url]</tt> or <tt>{long label}[url]</tt>
 
   def handle_special_TIDYLINK(special)
     text = special.text
@@ -232,8 +233,8 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
   end
 
   ##
-  # Generate a hyperlink for +url+, labeled with +text+.  Handles the special
-  # cases for img: and link: described under handle_special_HYPERLINK
+  # Generate a link for +url+, labeled with +text+.  Handles the special cases
+  # for img: and link: described under handle_special_HYPERLINK
 
   def gen_url(url, text)
     if url =~ /([A-Za-z]+):(.*)/ then

lib/rdoc/markup/to_html_crossref.rb

@@ -1,92 +1,19 @@
 require 'rdoc/markup/to_html'
+require 'rdoc/cross_reference'
 
 ##
-# Subclass of the RDoc::Markup::ToHtml class that supports looking up words
-# from a context.  Those that are found will be hyperlinked.
+# Subclass of the RDoc::Markup::ToHtml class that supports looking up method
+# names, classes, etc to create links.  RDoc::CrossReference is used to
+# generate those links based on the current context.
 
 class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
-  ##
-  # Regular expression to match class references
-  #
-  # 1. There can be a '\\' in front of text to suppress the cross-reference
-  # 2. There can be a '::' in front of class names to reference from the
-  #    top-level namespace.
-  # 3. The method can be followed by parenthesis (not recommended)
-
-  CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
-
-  ##
-  # Regular expression to match method references.
-  #
-  # See CLASS_REGEXP_STR
-
-  METHOD_REGEXP_STR = '([a-z]\w*[!?=]?)(?:\([\w.+*/=<>-]*\))?'
-
-  ##
-  # Regular expressions matching text that should potentially have
-  # cross-reference links generated are passed to add_special.  Note that
-  # these expressions are meant to pick up text for which cross-references
-  # have been suppressed, since the suppression characters are removed by the
-  # code that is triggered.
-
-  CROSSREF_REGEXP = /(
-                      # A::B::C.meth
-                      #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
-
-                      # Stand-alone method (preceded by a #)
-                      | \\?\##{METHOD_REGEXP_STR}
-
-                      # Stand-alone method (preceded by ::)
-                      | ::#{METHOD_REGEXP_STR}
-
-                      # A::B::C
-                      # The stuff after CLASS_REGEXP_STR is a
-                      # nasty hack.  CLASS_REGEXP_STR unfortunately matches
-                      # words like dog and cat (these are legal "class"
-                      # names in Fortran 95).  When a word is flagged as a
-                      # potential cross-reference, limitations in the markup
-                      # engine suppress other processing, such as typesetting.
-                      # This is particularly noticeable for contractions.
-                      # In order that words like "can't" not
-                      # be flagged as potential cross-references, only
-                      # flag potential class cross-references if the character
-                      # after the cross-reference is a space, sentence
-                      # punctuation, tag start character, or attribute
-                      # marker.
-                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
-
-                      # Things that look like filenames
-                      # The key thing is that there must be at least
-                      # one special character (period, slash, or
-                      # underscore).
-                      | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
-
-                      # Things that have markup suppressed
-                      # Don't process things like '\<' in \<tt>, though.
-                      # TODO: including < is a hack, not very satisfying.
-                      | \\[^\s<]
-                      )/x
-
-  ##
-  # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.
-
-  ALL_CROSSREF_REGEXP = /(
-                      # A::B::C.meth
-                      #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
-
-                      # Stand-alone method
-                      | \\?#{METHOD_REGEXP_STR}
-
-                      # A::B::C
-                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;<\000]|\z)
-
-                      # Things that look like filenames
-                      | (?:\.\.\/)*[-\/\w]+[_\/\.][-\w\/\.]+
-
-                      # Things that have markup suppressed
-                      | \\[^\s<]
-                      )/x
+  # :stopdoc:
+  ALL_CROSSREF_REGEXP = RDoc::CrossReference::ALL_CROSSREF_REGEXP
+  CLASS_REGEXP_STR    = RDoc::CrossReference::CLASS_REGEXP_STR
+  CROSSREF_REGEXP     = RDoc::CrossReference::CROSSREF_REGEXP
+  METHOD_REGEXP_STR   = RDoc::CrossReference::METHOD_REGEXP_STR
+  # :startdoc:
 
   ##
   # RDoc::CodeObject for generating references
@@ -102,7 +29,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   # Creates a new crossref resolver that generates links relative to +context+
   # which lives at +from_path+ in the generated files.  '#' characters on
   # references are removed unless +show_hash+ is true.  Only method names
-  # preceded by '#' or '::' are hyperlinked, unless +hyperlink_all+ is true.
+  # preceded by '#' or '::' are linked, unless +hyperlink_all+ is true.
 
   def initialize(from_path, context, show_hash, hyperlink_all = false,
                  markup = nil)
@@ -111,22 +38,36 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     crossref_re = hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
 
+    @cross_reference = RDoc::CrossReference.new context
+
     @markup.add_special crossref_re, :CROSSREF
+    @markup.add_special(/rdoc-ref:\S+\w/, :HYPERLINK)
 
-    @from_path = from_path
-    @context = context
-    @show_hash = show_hash
+    @from_path     = from_path
     @hyperlink_all = hyperlink_all
+    @show_hash     = show_hash
+  end
 
-    @seen = {}
+  ##
+  # Creates a link to the reference +name+ if the name exists.  If +text+ is
+  # given it is used as the link text, otherwise +name+ is used.
+
+  def cross_reference name, text = nil
+    lookup = name
+
+    name = name[1..-1] unless @show_hash if name[0, 1] == '#'
+
+    text = name unless text
+
+    link lookup, text
   end
 
   ##
   # We're invoked when any text matches the CROSSREF pattern.  If we find the
-  # corresponding reference, generate a hyperlink.  If the name we're looking
-  # for contains no punctuation, we look for it up the module/class chain.
-  # For example, ToHtml is found, even without the <tt>RDoc::Markup::</tt>
-  # prefix, because we look for it in module Markup first.
+  # corresponding reference, generate a link.  If the name we're looking for
+  # contains no punctuation, we look for it up the module/class chain.  For
+  # example, ToHtml is found, even without the <tt>RDoc::Markup::</tt> prefix,
+  # because we look for it in module Markup first.
 
   def handle_special_CROSSREF(special)
     name = special.text
@@ -138,66 +79,41 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
       return name if name =~ /\A[a-z]*\z/
     end
 
-    return @seen[name] if @seen.include? name
+    cross_reference name
+  end
 
-    lookup = name
+  ##
+  # Handles <tt>rdoc-ref:</tt> scheme links and allows RDoc::Markup::ToHtml to
+  # handle other schemes.
 
-    name = name[1..-1] unless @show_hash if name[0, 1] == '#'
+  def handle_special_HYPERLINK special
+    return cross_reference $' if special.text =~ /\Ardoc-ref:/
 
-    # Find class, module, or method in class or module.
-    #
-    # Do not, however, use an if/elsif/else chain to do so.  Instead, test
-    # each possible pattern until one matches.  The reason for this is that a
-    # string like "YAML.txt" could be the txt() class method of class YAML (in
-    # which case it would match the first pattern, which splits the string
-    # into container and method components and looks up both) or a filename
-    # (in which case it would match the last pattern, which just checks
-    # whether the string as a whole is a known symbol).
+    super
+  end
 
-    if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/ =~ lookup then
-      type = $2
-      type = '' if type == '.'  # will find either #method or ::method
-      method = "#{type}#{$3}"
-      container = @context.find_symbol_module($1)
-    elsif /^([.#]|::)#{METHOD_REGEXP_STR}/ =~ lookup then
-      type = $1
-      type = '' if type == '.'
-      method = "#{type}#{$2}"
-      container = @context
+  ##
+  # Generates links for <tt>rdoc-ref:</tt> scheme URLs and allows
+  # RDoc::Markup::ToHtml to handle other schemes.
+
+  def gen_url url, text
+    super unless url =~ /\Ardoc-ref:/
+
+    cross_reference $', text
+  end
+
+  ##
+  # Creates an HTML link to +name+ with the given +text+.
+
+  def link name, text
+    ref = @cross_reference.resolve name, text
+
+    case ref
+    when String then
+      ref
     else
-      container = nil
+      "<a href=\"#{ref.as_href @from_path}\">#{text}</a>"
     end
-
-    if container then
-      ref = container.find_local_symbol method
-
-      unless ref || RDoc::TopLevel === container then
-        ref = container.find_ancestor_local_symbol method
-      end
-    end
-
-    ref = @context.find_symbol lookup unless ref
-    ref = nil if RDoc::Alias === ref # external alias: can't link to it
-
-    out = if lookup == '\\' then
-            lookup
-          elsif lookup =~ /^\\/ then
-            # we remove the \ only in front of what we know:
-            # other backslashes are treated later, only outside of <tt>
-            ref ? $' : lookup
-          elsif ref then
-            if ref.document_self then
-              "<a href=\"#{ref.as_href @from_path}\">#{name}</a>"
-            else
-              name
-            end
-          else
-            lookup
-          end
-
-    @seen[lookup] = out
-
-    out
   end
 
 end

lib/rdoc/parser.rb

@@ -106,6 +106,8 @@ class RDoc::Parser
   # Applies +directive+'s +value+ to +code_object+, if appropriate
 
   def self.process_directive code_object, directive, value
+    warn "RDoc::Parser::process_directive is deprecated and wil be removed in RDoc 4.  Use RDoc::Markup::PreProcess#handle_directive instead" if $-w
+
     case directive
     when 'nodoc' then
       code_object.document_self = nil # notify nodoc
@@ -196,6 +198,9 @@ class RDoc::Parser
     @content = content
     @options = options
     @stats = stats
+
+    @preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
+    @preprocess.options = @options
   end
 
 end

lib/rdoc/parser/c.rb

@@ -645,9 +645,7 @@ class RDoc::Parser::C < RDoc::Parser
       meth_obj.call_seq = $1.strip
     end
 
-    if comment.sub!(/\s*:(nodoc|doc|yields?|args?):\s*(.*)/, '') then
-      RDoc::Parser.process_directive meth_obj, $1, $2
-    end
+    look_for_directives_in meth_obj, comment
   end
 
   ##
@@ -913,12 +911,10 @@ class RDoc::Parser::C < RDoc::Parser
   #    * :title: My Awesome Project
   #    */
   #
-  # This routine modifies its parameter
+  # This method modifies the +comment+
 
-  def look_for_directives_in(context, comment)
-    preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
-
-    preprocess.handle comment, context do |directive, param|
+  def look_for_directives_in context, comment
+    @preprocess.handle comment, context do |directive, param|
       case directive
       when 'main' then
         @options.main_page = param

lib/rdoc/parser/ruby.rb

@@ -405,17 +405,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
   #
   # This routine modifies its +comment+ parameter.
 
-  def look_for_directives_in(context, comment)
-    preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
-
-    preprocess.handle comment, context do |directive, param|
+  def look_for_directives_in context, comment
+    @preprocess.handle comment, context do |directive, param|
       case directive
-      when 'enddoc' then
-        context.done_documenting = true
-        ''
-      when 'main' then
-        @options.main_page = param if @options.respond_to? :main_page
-        ''
       when 'method', 'singleton-method',
            'attr', 'attr_accessor', 'attr_reader', 'attr_writer' then
         false # handled elsewhere
@@ -423,16 +415,6 @@ class RDoc::Parser::Ruby < RDoc::Parser
         context.set_current_section param, comment
         comment.replace ''
         break
-      when 'startdoc' then
-        context.start_doc
-        context.force_documentation = true
-        ''
-      when 'stopdoc' then
-        context.stop_doc
-        ''
-      when 'title' then
-        @options.default_title = param if @options.respond_to? :default_title=
-        ''
       end
     end
 
@@ -629,6 +611,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
       cls_type = single == SINGLE ? RDoc::SingleClass : RDoc::NormalClass
       cls = declaration_context.add_class cls_type, given_name, superclass
+      cls.ignore unless container.document_children
 
       read_documentation_modifiers cls, RDoc::CLASS_MODIFIERS
       cls.record_location @top_level
@@ -679,7 +662,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
   ##
   # Parses a constant in +context+ with +comment+
 
-  def parse_constant(container, tk, comment)
+  def parse_constant container, tk, comment
     offset  = tk.seek
     line_no = tk.line_no
 
@@ -718,7 +701,8 @@ class RDoc::Parser::Ruby < RDoc::Parser
       when TkRPAREN, TkRBRACE, TkRBRACK, TkEND then
         nest -= 1
       when TkCOMMENT then
-        if nest <= 0 && @scanner.lex_state == EXPR_END
+        if nest <= 0 &&
+           (@scanner.lex_state == EXPR_END || !@scanner.continue) then
           unget_tk tk
           break
         end
@@ -733,7 +717,6 @@ class RDoc::Parser::Ruby < RDoc::Parser
                 end
 
           container.add_module_alias mod, name, @top_level if mod
-          get_tk # TkNL
           break
         end
       when TkNL then
@@ -1327,11 +1310,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
         keep_comment = true
 
       when TkCLASS then
-        if container.document_children then
-          parse_class container, single, tk, comment
-        else
-          nest += 1
-        end
+        parse_class container, single, tk, comment
 
       when TkMODULE then
         if container.document_children then
@@ -1516,11 +1495,13 @@ class RDoc::Parser::Ruby < RDoc::Parser
   ##
   # Parses statements in the top-level +container+
 
-  def parse_top_level_statements(container)
+  def parse_top_level_statements container
     comment = collect_first_comment
-    look_for_directives_in(container, comment)
+    look_for_directives_in container, comment
+
     # HACK move if to RDoc::Context#comment=
     container.comment = comment if container.document_self unless comment.empty?
+
     parse_statements container, NORMAL, nil, comment
   end
 
@@ -1643,16 +1624,17 @@ class RDoc::Parser::Ruby < RDoc::Parser
   # Handles the directive for +context+ if the directive is listed in +allow+.
   # This method is called for directives following a definition.
 
-  def read_documentation_modifiers(context, allow)
+  def read_documentation_modifiers context, allow
     directive, value = read_directive allow
 
     return unless directive
 
-    case directive
-    when 'notnew', 'not_new', 'not-new' then
-      context.dont_rename_initialize = true
-    else
-      RDoc::Parser.process_directive context, directive, value
+    @preprocess.handle_directive '', directive, value, context do |dir, param|
+      if %w[notnew not_new not-new].include? dir then
+        context.dont_rename_initialize = true
+
+        true
+      end
     end
   end
 

lib/rdoc/parser/ruby_tools.rb

@@ -153,6 +153,8 @@ module RDoc::Parser::RubyTools
     @token_listeners.each do |obj|
       obj.pop_token
     end if @token_listeners
+
+    nil
   end
 
 end

lib/rdoc/ri/driver.rb

@@ -387,6 +387,8 @@ Options may also be set in the 'RI' environment variable.
                   klass.superclass unless klass.module?
                 end.compact.shift || 'Object'
 
+                superclass = superclass.full_name unless String === superclass
+
                 "#{name} < #{superclass}"
               end
 
@@ -451,7 +453,7 @@ Options may also be set in the 'RI' environment variable.
   # Adds a list of +methods+ to +out+ with a heading of +name+
 
   def add_method_list out, methods, name
-    return unless methods
+    return if methods.empty?
 
     out << RDoc::Markup::Heading.new(1, "#{name}:")
     out << RDoc::Markup::BlankLine.new
@@ -518,11 +520,13 @@ Options may also be set in the 'RI' environment variable.
 
     found.each do |store, klass|
       comment = klass.comment
-      class_methods    = store.class_methods[klass.full_name]
-      instance_methods = store.instance_methods[klass.full_name]
-      attributes       = store.attributes[klass.full_name]
+      # TODO the store's cache should always return an empty Array
+      class_methods    = store.class_methods[klass.full_name]    || []
+      instance_methods = store.instance_methods[klass.full_name] || []
+      attributes       = store.attributes[klass.full_name]       || []
 
-      if comment.empty? and !(instance_methods or class_methods) then
+      if comment.empty? and
+         instance_methods.empty? and class_methods.empty? then
         also_in << store
         next
       end
@@ -531,7 +535,17 @@ Options may also be set in the 'RI' environment variable.
 
       unless comment.empty? then
         out << RDoc::Markup::Rule.new(1)
-        out << comment
+
+        if comment.merged? then
+          parts = comment.parts
+          parts = parts.zip [RDoc::Markup::BlankLine.new] * parts.length
+          parts.flatten!
+          parts.pop
+
+          out.push(*parts)
+        else
+          out << comment
+        end
       end
 
       if class_methods or instance_methods or not klass.constants.empty? then
@@ -554,13 +568,12 @@ Options may also be set in the 'RI' environment variable.
         end)
 
         out << list
+        out << RDoc::Markup::BlankLine.new
       end
 
       add_method_list out, class_methods,    'Class methods'
       add_method_list out, instance_methods, 'Instance methods'
       add_method_list out, attributes,       'Attributes'
-
-      out << RDoc::Markup::BlankLine.new
     end
 
     add_also_in out, also_in
@@ -1090,11 +1103,11 @@ Options may also be set in the 'RI' environment variable.
   # NOTE: Given Foo::Bar, Bar is considered a class even though it may be a
   #       method
 
-  def parse_name(name)
+  def parse_name name
     parts = name.split(/(::|#|\.)/)
 
     if parts.length == 1 then
-      if parts.first =~ /^[a-z]/ then
+      if parts.first =~ /^[a-z]|^([%&*+\/<>^`|~-]|\+@|-@|<<|<=>?|===?|=>|=~|>>|\[\]=?|~@)$/ then
         type = '.'
         meth = parts.pop
       else

test/rdoc/test_rdoc_code_object.rb

@@ -67,6 +67,30 @@ class TestRDocCodeObject < XrefTestCase
     assert_equal Encoding::UTF_8, @co.comment.encoding
   end
 
+  def test_display_eh_document_self
+    assert @co.display?
+
+    @co.document_self = false
+
+    refute @co.display?
+  end
+
+  def test_display_eh_ignore
+    assert @co.display?
+
+    @co.ignore
+
+    refute @co.display?
+
+    @co.stop_doc
+
+    refute @co.display?
+
+    @co.done_documenting = false
+
+    refute @co.display?
+  end
+
   def test_document_children_equals
     @co.document_children = false
     refute @co.document_children
@@ -156,6 +180,22 @@ class TestRDocCodeObject < XrefTestCase
     assert_nil @co.instance_variable_get(:@full_name)
   end
 
+  def test_ignore
+    @co.ignore
+
+    refute @co.document_self
+    refute @co.document_children
+    assert @co.ignored?
+  end
+
+  def test_ignore_eh
+    refute @co.ignored?
+
+    @co.ignore
+
+    assert @co.ignored?
+  end
+
   def test_line
     @c1_m.line = 5
 
@@ -202,10 +242,16 @@ class TestRDocCodeObject < XrefTestCase
   end
 
   def test_record_location
-    c = RDoc::CodeObject.new
-    c.record_location @xref_data
+    @co.record_location @xref_data
 
-    assert_equal 'xref_data.rb', c.file.relative_name
+    assert_equal 'xref_data.rb', @co.file.relative_name
+  end
+
+  def test_record_location_ignored
+    @co.ignore
+    @co.record_location @xref_data
+
+    refute @co.ignored?
   end
 
   def test_start_doc
@@ -218,6 +264,16 @@ class TestRDocCodeObject < XrefTestCase
     assert @co.document_children
   end
 
+  def test_start_doc_ignored
+    @co.ignore
+
+    @co.start_doc
+
+    assert @co.document_self
+    assert @co.document_children
+    refute @co.ignored?
+  end
+
   def test_stop_doc
     @co.document_self = true
     @co.document_children = true

test/rdoc/test_rdoc_cross_reference.rb

@@ -0,0 +1,154 @@
+require 'rubygems'
+require 'minitest/autorun'
+require File.expand_path '../xref_test_case', __FILE__
+
+class TestRDocCrossReference < XrefTestCase
+
+  def setup
+    super
+
+    @xref = RDoc::CrossReference.new @c1
+  end
+
+  def assert_ref expected, name
+    assert_equal expected, @xref.resolve(name, 'fail')
+  end
+
+  def refute_ref name
+    assert_equal name, @xref.resolve(name, name)
+  end
+
+  def test_resolve_C2
+    @xref = RDoc::CrossReference.new @c2
+
+    refute_ref '#m'
+
+    assert_ref @c1__m,    'C1::m'
+    assert_ref @c2_c3,    'C2::C3'
+    assert_ref @c2_c3_m,  'C2::C3#m'
+    assert_ref @c2_c3_h1, 'C3::H1'
+    assert_ref @c4,       'C4'
+
+    assert_ref @c3_h2, 'C3::H2'
+    refute_ref 'H1'
+  end
+
+  def test_resolve_C2_C3
+    @xref = RDoc::CrossReference.new @c2_c3
+
+    assert_ref @c2_c3_m, '#m'
+
+    assert_ref @c2_c3, 'C3'
+    assert_ref @c2_c3_m, 'C3#m'
+
+    assert_ref @c2_c3_h1, 'H1'
+    assert_ref @c2_c3_h1, 'C3::H1'
+
+    assert_ref @c4, 'C4'
+
+    assert_ref @c3_h2, 'C3::H2'
+  end
+
+  def test_resolve_C3
+    @xref = RDoc::CrossReference.new @c3
+
+    assert_ref @c3, 'C3'
+
+    refute_ref '#m'
+    refute_ref 'C3#m'
+
+    assert_ref @c3_h1, 'H1'
+
+    assert_ref @c3_h1, 'C3::H1'
+    assert_ref @c3_h2, 'C3::H2'
+
+    assert_ref @c4, 'C4'
+  end
+
+  def test_resolve_C4
+    @xref = RDoc::CrossReference.new @c4
+
+    # C4 ref inside a C4 containing a C4 should resolve to the contained class
+    assert_ref @c4_c4, 'C4'
+  end
+
+  def test_resolve_C4_C4
+    @xref = RDoc::CrossReference.new @c4_c4
+
+    # A C4 reference inside a C4 class contained within a C4 class should
+    # resolve to the inner C4 class.
+    assert_ref @c4_c4, 'C4'
+  end
+
+  def test_resolve_class
+    assert_ref @c1, 'C1'
+    refute_ref 'H1'
+
+    assert_ref @c2,       'C2'
+    assert_ref @c2_c3,    'C2::C3'
+    assert_ref @c2_c3_h1, 'C2::C3::H1'
+
+    assert_ref @c3,    '::C3'
+    assert_ref @c3_h1, '::C3::H1'
+
+    assert_ref @c4_c4, 'C4::C4'
+  end
+
+  def test_resolve_file
+    assert_ref @xref_data, 'xref_data.rb'
+  end
+
+  def test_resolve_method
+    assert_ref @c1__m, 'm'
+    assert_ref @c1_m,  '#m'
+    assert_ref @c1__m, '::m'
+
+    assert_ref @c1_m,  'C1#m'
+    assert_ref @c1__m, 'C1.m'
+    assert_ref @c1__m, 'C1::m'
+
+    assert_ref @c1_m, 'C1#m'
+    assert_ref @c1_m, 'C1#m()'
+    assert_ref @c1_m, 'C1#m(*)'
+
+    assert_ref @c1__m, 'C1.m'
+    assert_ref @c1__m, 'C1.m()'
+    assert_ref @c1__m, 'C1.m(*)'
+
+    assert_ref @c1__m, 'C1::m'
+    assert_ref @c1__m, 'C1::m()'
+    assert_ref @c1__m, 'C1::m(*)'
+
+    assert_ref @c2_c3_m, 'C2::C3#m'
+
+    assert_ref @c2_c3_m, 'C2::C3.m'
+
+    # TODO stop escaping - HTML5 allows anything but space
+    assert_ref @c2_c3_h1_meh, 'C2::C3::H1#m?'
+
+    assert_ref @c2_c3_m, '::C2::C3#m'
+    assert_ref @c2_c3_m, '::C2::C3#m()'
+    assert_ref @c2_c3_m, '::C2::C3#m(*)'
+  end
+
+  def test_resolve_no_ref
+    assert_equal '', @xref.resolve('', '')
+
+    assert_equal "bogus",     @xref.resolve("bogus",     "bogus")
+    assert_equal "\\bogus",   @xref.resolve("\\bogus",   "\\bogus")
+    assert_equal "\\\\bogus", @xref.resolve("\\\\bogus", "\\\\bogus")
+
+    assert_equal "\\#n",    @xref.resolve("\\#n",    "fail")
+    assert_equal "\\#n()",  @xref.resolve("\\#n()",  "fail")
+    assert_equal "\\#n(*)", @xref.resolve("\\#n(*)", "fail")
+
+    assert_equal "C1",   @xref.resolve("\\C1",   "fail")
+    assert_equal "::C3", @xref.resolve("\\::C3", "fail")
+
+    assert_equal "succeed",      @xref.resolve("::C3::H1#n",    "succeed")
+    assert_equal "succeed",      @xref.resolve("::C3::H1#n(*)", "succeed")
+    assert_equal "\\::C3::H1#n", @xref.resolve("\\::C3::H1#n",  "fail")
+  end
+
+end
+

test/rdoc/test_rdoc_generator_darkfish.rb

@@ -38,6 +38,7 @@ class TestRDocGeneratorDarkfish < MiniTest::Unit::TestCase
 
     @top_level = RDoc::TopLevel.new 'file.rb'
     @klass = @top_level.add_class RDoc::NormalClass, 'Object'
+
     @meth = RDoc::AnyMethod.new nil, 'method'
     @meth_bang = RDoc::AnyMethod.new nil, 'method!'
     @attr = RDoc::Attr.new nil, 'attr', 'RW', ''
@@ -45,6 +46,9 @@ class TestRDocGeneratorDarkfish < MiniTest::Unit::TestCase
     @klass.add_method @meth
     @klass.add_method @meth_bang
     @klass.add_attribute @attr
+
+    @ignored = @top_level.add_class RDoc::NormalClass, 'Ignored'
+    @ignored.ignore
   end
 
   def teardown
@@ -83,6 +87,8 @@ class TestRDocGeneratorDarkfish < MiniTest::Unit::TestCase
                  File.read('Object.html'))
     assert_match(/<meta content="text\/html; charset=#{encoding}"/,
                  File.read('file_rb.html'))
+
+    refute_match(/Ignored/, File.read('index.html'))
   end
 
   def test_generate_dry_run

test/rdoc/test_rdoc_markup_document.rb

@@ -124,6 +124,24 @@ class TestRDocMarkupDocument < MiniTest::Unit::TestCase
     assert_equal expected, result
   end
 
+  def test_merge_empty
+    original = @RM::Document.new
+    root = @RM::Document.new original
+
+    replace = @RM::Document.new @RM::Paragraph.new 'replace'
+    replace.file = 'file.rb'
+
+    other = @RM::Document.new replace
+
+    result = root.merge other
+
+    inner = @RM::Document.new @RM::Paragraph.new 'replace'
+    inner.file = 'file.rb'
+    expected = @RM::Document.new inner
+
+    assert_equal expected, result
+  end
+
   def test_push
     @d.push @RM::BlankLine.new, @RM::BlankLine.new
 

test/rdoc/test_rdoc_markup_parser.rb

@@ -1366,6 +1366,44 @@ Example heading:
     assert_equal expected, @RMP.tokenize(str)
   end
 
+  def test_tokenize_verbatim_rule
+    str = <<-STR
+  Verbatim section here that is double-underlined
+  ===============================================
+    STR
+
+    expected = [
+      [:TEXT,    'Verbatim section here that is double-underlined',  2, 0],
+      [:NEWLINE, "\n",                                              49, 0],
+      [:HEADER,  47,                                                 2, 1],
+      [:NEWLINE, "\n",                                              49, 1],
+    ]
+
+    assert_equal expected, @RMP.tokenize(str)
+  end
+
+  def test_tokenize_verbatim_rule_fancy
+    str = <<-STR
+  A
+    b
+  ===============================================
+    c
+    STR
+
+    expected = [
+      [:TEXT,    'A',   2, 0],
+      [:NEWLINE, "\n",  3, 0],
+      [:TEXT,    'b',   4, 1],
+      [:NEWLINE, "\n",  5, 1],
+      [:HEADER,  47,    2, 2],
+      [:NEWLINE, "\n", 49, 2],
+      [:TEXT,    'c',   4, 3],
+      [:NEWLINE, "\n",  5, 3],
+    ]
+
+    assert_equal expected, @RMP.tokenize(str)
+  end
+
   # HACK move to Verbatim test case
   def test_verbatim_normalize
     v = @RM::Verbatim.new "foo\n", "\n", "\n", "bar\n"

test/rdoc/test_rdoc_markup_pre_process.rb

@@ -5,6 +5,7 @@ require 'rubygems'
 require 'minitest/autorun'
 require 'rdoc/markup/pre_process'
 require 'rdoc/code_objects'
+require 'rdoc/options'
 
 class TestRDocMarkupPreProcess < MiniTest::Unit::TestCase
 
@@ -19,6 +20,8 @@ class TestRDocMarkupPreProcess < MiniTest::Unit::TestCase
   end
 
   def teardown
+    RDoc::Markup::PreProcess.registered.clear
+
     @tempfile.close
   end
 
@@ -73,6 +76,14 @@ contents of a string.
   end
 
   def test_handle
+    text = "# :main: M\n"
+    out = @pp.handle text
+
+    assert_same out, text
+    assert_equal "#\n", text
+  end
+
+  def test_handle_unregistered
     text = "# :x: y\n"
     out = @pp.handle text
 
@@ -80,142 +91,329 @@ contents of a string.
     assert_equal "# :x: y\n", text
   end
 
-  def test_handle_block
-    text = "# :x: y\n"
+  def test_handle_directive_blankline
+    result = @pp.handle_directive '#', 'arg', 'a, b'
 
-    @pp.handle text do |directive, param|
-      false
-    end
+    assert_equal "#\n", result
+  end
 
-    assert_equal "# :x: y\n", text
+  def test_handle_directive_downcase
+    method = RDoc::AnyMethod.new nil, 'm'
 
-    @pp.handle text do |directive, param|
+    @pp.handle_directive '', 'ARG', 'a, b', method
+
+    assert_equal 'a, b', method.params
+  end
+
+  def test_handle_directive_arg
+    method = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'arg', 'a, b', method
+
+    assert_equal 'a, b', method.params
+  end
+
+  def test_handle_directive_arg_no_context
+    result = @pp.handle_directive '', 'arg', 'a, b', nil
+
+    assert_equal "\n", result
+  end
+
+  def test_handle_directive_args
+    method = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'args', 'a, b', method
+
+    assert_equal 'a, b', method.params
+  end
+
+  def test_handle_directive_block
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       ''
     end
 
-    assert_equal "", text
+    assert_empty result
   end
 
-  def test_handle_category
+  def test_handle_directive_block_false
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
+      false
+    end
+
+    assert_equal ":x: y\n", result
+  end
+
+  def test_handle_directive_block_nil
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
+      nil
+    end
+
+    assert_equal ":x: y\n", result
+  end
+
+  def test_handle_directive_category
     context = RDoc::Context.new
     original_section = context.current_section
 
-    text = "# :category: other\n"
-
-    @pp.handle text, context
+    @pp.handle_directive '', 'category', 'other', context
 
     refute_equal original_section, context.current_section
   end
 
-  def test_handle_code_object
-    cd = RDoc::CodeObject.new
-    text = "# :x: y\n"
-    @pp.handle text, cd
+  def test_handle_directive_doc
+    code_object = RDoc::CodeObject.new
+    code_object.document_self = false
+    code_object.force_documentation = false
 
-    assert_equal "# :x: y\n", text
-    assert_equal 'y', cd.metadata['x']
+    @pp.handle_directive '', 'doc', nil, code_object
 
-    cd.metadata.clear
-    text = "# :x:\n"
-    @pp.handle text, cd
-
-    assert_equal "# :x: \n", text
-    assert_includes cd.metadata, 'x'
+    assert code_object.document_self
+    assert code_object.force_documentation
   end
 
-  def test_handle_code_object_block
-    cd = RDoc::CodeObject.new
-    text = "# :x: y\n"
-    @pp.handle text, cd do
-      false
-    end
+  def test_handle_directive_doc_no_context
+    result = @pp.handle_directive '', 'doc', nil
 
-    assert_equal "# :x: y\n", text
-    assert_empty cd.metadata
-
-    @pp.handle text, cd do
-      nil
-    end
-
-    assert_equal "# :x: y\n", text
-    assert_equal 'y', cd.metadata['x']
-
-    cd.metadata.clear
-
-    @pp.handle text, cd do
-      ''
-    end
-
-    assert_equal '', text
-    assert_empty cd.metadata
+    assert_equal "\n", result
   end
 
-  def test_handle_registered
+  def test_handle_directive_enddoc
+    code_object = RDoc::CodeObject.new
+
+    @pp.handle_directive '', 'enddoc', nil, code_object
+
+    assert code_object.done_documenting
+  end
+
+  def test_handle_directive_include
+    @tempfile.write 'included'
+    @tempfile.flush
+
+    result = @pp.handle_directive '', 'include', @file_name
+
+    assert_equal 'included', result
+  end
+
+  def test_handle_directive_main
+    @pp.options = RDoc::Options.new
+
+    @pp.handle_directive '', 'main', 'M'
+
+    assert_equal 'M', @pp.options.main_page
+  end
+
+  def test_handle_directive_notnew
+    m = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'notnew', nil, m
+
+    assert m.dont_rename_initialize
+  end
+
+  def test_handle_directive_not_new
+    m = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'not_new', nil, m
+
+    assert m.dont_rename_initialize
+  end
+
+  def test_handle_directive_not_dash_new
+    m = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'not-new', nil, m
+
+    assert m.dont_rename_initialize
+  end
+
+  def test_handle_directive_nodoc
+    code_object = RDoc::CodeObject.new
+    code_object.document_self = true
+    code_object.document_children = true
+
+    @pp.handle_directive '', 'nodoc', nil, code_object
+
+    refute code_object.document_self
+    assert code_object.document_children
+  end
+
+  def test_handle_directive_nodoc_all
+    code_object = RDoc::CodeObject.new
+    code_object.document_self = true
+    code_object.document_children = true
+
+    @pp.handle_directive '', 'nodoc', 'all', code_object
+
+    refute code_object.document_self
+    refute code_object.document_children
+  end
+
+  def test_handle_directive_nodoc_no_context
+    result = @pp.handle_directive '', 'nodoc', nil
+
+    assert_equal "\n", result
+  end
+
+  def test_handle_directive_registered
     RDoc::Markup::PreProcess.register 'x'
-    text = "# :x: y\n"
-    @pp.handle text
 
-    assert_equal '', text
+    result = @pp.handle_directive '', 'x', 'y'
 
-    text = "# :x: y\n"
+    assert_nil result
 
-    @pp.handle text do |directive, param|
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       false
     end
 
-    assert_equal "# :x: y\n", text
+    assert_equal ":x: y\n", result
 
-    text = "# :x: y\n"
-
-    @pp.handle text do |directive, param|
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       ''
     end
 
-    assert_equal "", text
+    assert_equal '', result
   end
 
-  def test_handle_registered_block
+  def test_handle_directive_registered_block
     called = nil
+
     RDoc::Markup::PreProcess.register 'x' do |directive, param|
       called = [directive, param]
       'blah'
     end
 
-    text = "# :x: y\n"
-    @pp.handle text
+    result = @pp.handle_directive '', 'x', 'y'
 
-    assert_equal 'blah', text
+    assert_equal 'blah', result
     assert_equal %w[x y], called
   end
 
-  def test_handle_registered_code_object
+  def test_handle_directive_registered_code_object
     RDoc::Markup::PreProcess.register 'x'
-    cd = RDoc::CodeObject.new
+    code_object = RDoc::CodeObject.new
 
-    text = "# :x: y\n"
-    @pp.handle text, cd
+    @pp.handle_directive '', 'x', 'y', code_object
 
-    assert_equal '', text
-    assert_equal 'y', cd.metadata['x']
+    assert_equal 'y', code_object.metadata['x']
 
-    cd.metadata.clear
-    text = "# :x: y\n"
+    code_object.metadata.clear
 
-    @pp.handle text do |directive, param|
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       false
     end
 
-    assert_equal "# :x: y\n", text
-    assert_empty cd.metadata
+    assert_equal ":x: y\n", result
+    assert_empty code_object.metadata
 
-    text = "# :x: y\n"
-
-    @pp.handle text do |directive, param|
+    result = @pp.handle_directive '', 'x', 'y' do |directive, param|
       ''
     end
 
-    assert_equal "", text
-    assert_empty cd.metadata
+    assert_equal '', result
+    assert_empty code_object.metadata
+  end
+
+  def test_handle_directive_startdoc
+    code_object = RDoc::CodeObject.new
+    code_object.stop_doc
+    code_object.force_documentation = false
+
+    @pp.handle_directive '', 'startdoc', nil, code_object
+
+    assert code_object.document_self
+    assert code_object.document_children
+    assert code_object.force_documentation
+  end
+
+  def test_handle_directive_stopdoc
+    code_object = RDoc::CodeObject.new
+
+    @pp.handle_directive '', 'stopdoc', nil, code_object
+
+    refute code_object.document_self
+    refute code_object.document_children
+  end
+
+  def test_handle_directive_title
+    @pp.options = RDoc::Options.new
+
+    @pp.handle_directive '', 'title', 'T'
+
+    assert_equal 'T', @pp.options.title
+  end
+
+  def test_handle_directive_unhandled
+    code_object = RDoc::CodeObject.new
+
+    @pp.handle_directive '', 'x', 'y', code_object
+
+    assert_equal 'y', code_object.metadata['x']
+
+    code_object.metadata.clear
+
+    @pp.handle_directive '', 'x', '', code_object
+
+    assert_includes code_object.metadata, 'x'
+  end
+
+  def test_handle_directive_unhandled_block
+    code_object = RDoc::CodeObject.new
+
+    @pp.handle_directive '', 'x', 'y', code_object do
+      false
+    end
+
+    assert_empty code_object.metadata
+
+    @pp.handle_directive '', 'x', 'y', code_object do
+      nil
+    end
+
+    assert_equal 'y', code_object.metadata['x']
+
+    code_object.metadata.clear
+
+    @pp.handle_directive '', 'x', 'y', code_object do
+      ''
+    end
+
+    assert_empty code_object.metadata
+  end
+
+  def test_handle_directive_yield
+    method = RDoc::AnyMethod.new nil, 'm'
+    method.params = 'index, &block'
+
+    @pp.handle_directive '', 'yield', 'item', method
+
+    assert_equal 'item', method.block_params
+    assert_equal 'index', method.params
+  end
+
+  def test_handle_directive_yield_block_param
+    method = RDoc::AnyMethod.new nil, 'm'
+    method.params = '&block'
+
+    @pp.handle_directive '', 'yield', 'item', method
+
+    assert_equal 'item', method.block_params
+    assert_empty method.params
+  end
+
+  def test_handle_directive_yield_no_context
+    method = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'yield', 'item', method
+
+    assert_equal 'item', method.block_params
+  end
+
+  def test_handle_directive_yields
+    method = RDoc::AnyMethod.new nil, 'm'
+
+    @pp.handle_directive '', 'yields', 'item', method
+
+    assert_equal 'item', method.block_params
   end
 
 end

test/rdoc/test_rdoc_markup_to_html.rb

@@ -306,6 +306,14 @@ class TestRDocMarkupToHtml < RDoc::Markup::FormatterTestCase
                  @to.gen_url('link:example', 'example')
   end
 
+  def test_handle_special_HYPERLINK_link
+    special = RDoc::Markup::Special.new 0, 'link:README.txt'
+
+    link = @to.handle_special_HYPERLINK special
+
+    assert_equal '<a href="README.txt">README.txt</a>', link
+  end
+
   def test_list_verbatim_2
     str = "* one\n    verb1\n    verb2\n* two\n"
 

test/rdoc/test_rdoc_markup_to_html_crossref.rb

@@ -10,159 +10,86 @@ class TestRDocMarkupToHtmlCrossref < XrefTestCase
   def setup
     super
 
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'index.html', @c1, true
+    @to = RDoc::Markup::ToHtmlCrossref.new 'index.html', @c1, true
   end
 
-  def assert_ref(path, ref)
-    assert_equal "\n<p><a href=\"#{path}\">#{ref}</a></p>\n", @xref.convert(ref)
+  def test_convert_CROSSREF
+    result = @to.convert 'C1'
+
+    assert_equal "\n<p><a href=\"C1.html\">C1</a></p>\n", result
   end
 
-  def refute_ref(body, ref)
-    assert_equal "\n<p>#{body}</p>\n", @xref.convert(ref)
+  def test_convert_HYPERLINK_rdoc_ref
+    result = @to.convert 'rdoc-ref:C1'
+
+    assert_equal "\n<p><a href=\"C1.html\">C1</a></p>\n", result
   end
 
-  def test_handle_special_CROSSREF_C2
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C2.html', @c2, true
-
-    refute_ref '#m', '#m'
-
-    assert_ref '../C1.html#method-c-m', 'C1::m'
-    assert_ref '../C2/C3.html', 'C2::C3'
-    assert_ref '../C2/C3.html#method-i-m', 'C2::C3#m'
-    assert_ref '../C2/C3/H1.html', 'C3::H1'
-    assert_ref '../C4.html', 'C4'
-
-    assert_ref '../C3/H2.html', 'C3::H2'
-    refute_ref 'H1', 'H1'
-  end
-
-  def test_handle_special_CROSSREF_C2_C3
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C2/C3.html', @c2_c3, true
-
-    assert_ref '../../C2/C3.html#method-i-m', '#m'
-
-    assert_ref '../../C2/C3.html', 'C3'
-    assert_ref '../../C2/C3.html#method-i-m', 'C3#m'
-
-    assert_ref '../../C2/C3/H1.html', 'H1'
-    assert_ref '../../C2/C3/H1.html', 'C3::H1'
-
-    assert_ref '../../C4.html', 'C4'
-
-    assert_ref '../../C3/H2.html', 'C3::H2'
-  end
-
-  def test_handle_special_CROSSREF_C3
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C3.html', @c3, true
-
-    assert_ref '../C3.html', 'C3'
-
-    refute_ref '#m',   '#m'
-    refute_ref 'C3#m', 'C3#m'
-
-    assert_ref '../C3/H1.html', 'H1'
-
-    assert_ref '../C3/H1.html', 'C3::H1'
-    assert_ref '../C3/H2.html', 'C3::H2'
-
-    assert_ref '../C4.html', 'C4'
-  end
-
-  def test_handle_special_CROSSREF_C4
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C4.html', @c4, true
-
-    # C4 ref inside a C4 containing a C4 should resolve to the contained class
-    assert_ref '../C4/C4.html', 'C4'
-  end
-
-  def test_handle_special_CROSSREF_C4_C4
-    @xref = RDoc::Markup::ToHtmlCrossref.new 'classes/C4/C4.html', @c4_c4, true
-
-    # A C4 reference inside a C4 class contained within a C4 class should
-    # resolve to the inner C4 class.
-    assert_ref '../../C4/C4.html', 'C4'
-  end
-
-  def test_handle_special_CROSSREF_class
-    assert_ref 'C1.html', 'C1'
-    refute_ref 'H1', 'H1'
-
-    assert_ref 'C2.html',       'C2'
-    assert_ref 'C2/C3.html',    'C2::C3'
-    assert_ref 'C2/C3/H1.html', 'C2::C3::H1'
-
-    assert_ref 'C3.html',    '::C3'
-    assert_ref 'C3/H1.html', '::C3::H1'
-
-    assert_ref 'C4/C4.html', 'C4::C4'
-  end
-
-  def test_handle_special_CROSSREF_file
-    assert_ref 'xref_data_rb.html', 'xref_data.rb'
-  end
-
-  def test_handle_special_CROSSREF_method
-    refute_ref 'm', 'm'
-    assert_ref 'C1.html#method-i-m', '#m'
-    assert_ref 'C1.html#method-c-m', '::m'
-
-    assert_ref 'C1.html#method-i-m', 'C1#m'
-    assert_ref 'C1.html#method-c-m', 'C1.m'
-    assert_ref 'C1.html#method-c-m', 'C1::m'
-
-    assert_ref 'C1.html#method-i-m', 'C1#m'
-    assert_ref 'C1.html#method-i-m', 'C1#m()'
-    assert_ref 'C1.html#method-i-m', 'C1#m(*)'
-
-    assert_ref 'C1.html#method-c-m', 'C1.m'
-    assert_ref 'C1.html#method-c-m', 'C1.m()'
-    assert_ref 'C1.html#method-c-m', 'C1.m(*)'
-
-    assert_ref 'C1.html#method-c-m', 'C1::m'
-    assert_ref 'C1.html#method-c-m', 'C1::m()'
-    assert_ref 'C1.html#method-c-m', 'C1::m(*)'
-
-    assert_ref 'C2/C3.html#method-i-m', 'C2::C3#m'
-
-    assert_ref 'C2/C3.html#method-i-m', 'C2::C3.m'
-
-    # TODO stop escaping - HTML5 allows anything but space
-    assert_ref 'C2/C3/H1.html#method-i-m-3F', 'C2::C3::H1#m?'
-
-    assert_ref 'C2/C3.html#method-i-m', '::C2::C3#m'
-    assert_ref 'C2/C3.html#method-i-m', '::C2::C3#m()'
-    assert_ref 'C2/C3.html#method-i-m', '::C2::C3#m(*)'
-  end
-
-  def test_handle_special_CROSSREF_no_ref
-    assert_equal '', @xref.convert('')
-
-    refute_ref 'bogus', 'bogus'
-    refute_ref 'bogus', '\bogus'
-    refute_ref '\bogus', '\\\bogus'
-
-    refute_ref '#n',    '\#n'
-    refute_ref '#n()',  '\#n()'
-    refute_ref '#n(*)', '\#n(*)'
-
-    refute_ref 'C1',   '\C1'
-    refute_ref '::C3', '\::C3'
-
-    refute_ref '::C3::H1#n',    '::C3::H1#n'
-    refute_ref '::C3::H1#n(*)', '::C3::H1#n(*)'
-    refute_ref '::C3::H1#n',    '\::C3::H1#n'
+  def test_handle_special_CROSSREF
+    assert_equal "<a href=\"C2/C3.html\">C2::C3</a>", SPECIAL('C2::C3')
   end
 
   def test_handle_special_CROSSREF_show_hash_false
-    @xref.show_hash = false
+    @to.show_hash = false
 
-    assert_equal "\n<p><a href=\"C1.html#method-i-m\">m</a></p>\n",
-                 @xref.convert('#m')
+    assert_equal "<a href=\"C1.html#method-i-m\">m</a>",
+                 SPECIAL('#m')
   end
 
-  def test_handle_special_CROSSREF_special
-    assert_equal "\n<p><a href=\"C2/C3.html\">C2::C3</a>;method(*)</p>\n",
-                 @xref.convert('C2::C3;method(*)')
+  def test_handle_special_HYPERLINK_rdoc
+    RDoc::TopLevel.new 'README.txt'
+    @to = RDoc::Markup::ToHtmlCrossref.new 'C2.html', @c2, true
+
+    link = @to.handle_special_HYPERLINK hyper 'C2::C3'
+
+    assert_equal '<a href="C2/C3.html">C2::C3</a>', link
+
+    link = @to.handle_special_HYPERLINK hyper 'C4'
+
+    assert_equal '<a href="C4.html">C4</a>', link
+
+    link = @to.handle_special_HYPERLINK hyper 'README.txt'
+
+    assert_equal '<a href="README_txt.html">README.txt</a>', link
+  end
+
+  def test_handle_special_TIDYLINK_rdoc
+    RDoc::TopLevel.new 'README.txt'
+    @to = RDoc::Markup::ToHtmlCrossref.new 'C2.html', @c2, true
+
+    link = @to.handle_special_TIDYLINK tidy 'C2::C3'
+
+    assert_equal '<a href="C2/C3.html">tidy</a>', link
+
+    link = @to.handle_special_TIDYLINK tidy 'C4'
+
+    assert_equal '<a href="C4.html">tidy</a>', link
+
+    link = @to.handle_special_TIDYLINK tidy 'README.txt'
+
+    assert_equal '<a href="README_txt.html">tidy</a>', link
+  end
+
+  def test_link
+    assert_equal 'n', @to.link('n', 'n')
+
+    assert_equal '<a href="C1.html#method-c-m">m</a>', @to.link('m', 'm')
+  end
+
+  def SPECIAL text
+    @to.handle_special_CROSSREF special text
+  end
+
+  def hyper reference
+    RDoc::Markup::Special.new 0, "rdoc-ref:#{reference}"
+  end
+
+  def special text
+    RDoc::Markup::Special.new 0, text
+  end
+
+  def tidy reference
+    RDoc::Markup::Special.new 0, "{tidy}[rdoc-ref:#{reference}]"
   end
 
 end

test/rdoc/test_rdoc_parser_ruby.rb

@@ -313,22 +313,6 @@ class C; end
                  comment
   end
 
-  def test_look_for_directives_in_enddoc
-    util_parser ""
-
-    @parser.look_for_directives_in @top_level, "# :enddoc:\n"
-
-    assert @top_level.done_documenting
-  end
-
-  def test_look_for_directives_in_main
-    util_parser ""
-
-    @parser.look_for_directives_in @top_level, "# :main: new main page\n"
-
-    assert_equal 'new main page', @options.main_page
-  end
-
   def test_look_for_directives_in_method
     util_parser ""
 
@@ -345,31 +329,6 @@ class C; end
     assert_equal "# :singleton-method: my_method\n", comment
   end
 
-  def test_look_for_directives_in_startdoc
-    util_parser ""
-
-    @top_level.stop_doc
-    assert !@top_level.document_self
-    assert !@top_level.document_children
-
-    @parser.look_for_directives_in @top_level, "# :startdoc:\n"
-
-    assert @top_level.document_self
-    assert @top_level.document_children
-  end
-
-  def test_look_for_directives_in_stopdoc
-    util_parser ""
-
-    assert @top_level.document_self
-    assert @top_level.document_children
-
-    @parser.look_for_directives_in @top_level, "# :stopdoc:\n"
-
-    assert !@top_level.document_self
-    assert !@top_level.document_children
-  end
-
   def test_look_for_directives_in_section
     util_parser ""
 
@@ -384,14 +343,6 @@ class C; end
     assert_equal '', comment
   end
 
-  def test_look_for_directives_in_title
-    util_parser ""
-
-    @parser.look_for_directives_in @top_level, "# :title: new title\n"
-
-    assert_equal 'new title', @options.title
-  end
-
   def test_look_for_directives_in_unhandled
     util_parser ""
 
@@ -797,12 +748,7 @@ end
 
     @parser.parse_class @top_level, RDoc::Parser::Ruby::NORMAL, tk, comment
 
-    foo = @top_level.classes.first
-    assert_equal 'Foo', foo.full_name
-    assert_equal 'my class', foo.comment
-    assert_equal [@top_level], foo.in_files
-    assert_equal 0, foo.offset
-    assert_equal 1, foo.line
+    assert_empty @top_level.classes.first.comment
   end
 
   def test_parse_multi_ghost_methods
@@ -2227,6 +2173,45 @@ end
     assert_empty @top_level.comment
   end
 
+  def test_parse_top_level_statements_stopdoc_integration
+    content = <<-CONTENT
+# :stopdoc:
+
+class Example
+  def method_name
+  end
+end
+    CONTENT
+
+    util_parser content
+
+    @parser.parse_top_level_statements @top_level
+
+    assert_equal 1, @top_level.classes.length
+    assert_empty @top_level.modules
+
+    assert @top_level.find_module_named('Example').ignored?
+  end
+
+  # This tests parse_comment
+  def test_parse_top_level_statements_constant_nodoc_integration
+    content = <<-CONTENT
+class A
+  C = A # :nodoc:
+end
+    CONTENT
+
+    util_parser content
+
+    @parser.parse_top_level_statements @top_level
+
+    klass = @top_level.find_module_named('A')
+
+    c = klass.constants.first
+
+    assert_nil c.document_self, 'C should not be documented'
+  end
+
   def test_parse_yield_in_braces_with_parens
     klass = RDoc::NormalClass.new 'Foo'
     klass.parent = @top_level

test/rdoc/test_rdoc_ri_driver.rb

@@ -5,6 +5,7 @@ require 'tmpdir'
 require 'fileutils'
 require 'stringio'
 require 'rdoc/ri/driver'
+require 'rdoc/rdoc'
 
 class TestRDocRIDriver < MiniTest::Unit::TestCase
 
@@ -223,7 +224,7 @@ class TestRDocRIDriver < MiniTest::Unit::TestCase
   def test_add_method_list_none
     out = @RM::Document.new
 
-    @driver.add_method_list out, nil, 'Class'
+    @driver.add_method_list out, [], 'Class'
 
     assert_equal @RM::Document.new, out
   end
@@ -249,6 +250,46 @@ class TestRDocRIDriver < MiniTest::Unit::TestCase
     assert_equal expected, @driver.classes
   end
 
+  def test_class_document
+    util_store
+
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
+    @cFoo.add_comment 'one', tl1
+    @cFoo.add_comment 'two', tl2
+    @store.save_class @cFoo
+
+    found = [
+      [@store, @store.load_class(@cFoo.full_name)]
+    ]
+
+    out = @driver.class_document @cFoo.full_name, found, [], []
+
+    expected = @RM::Document.new
+    @driver.add_class expected, 'Foo', []
+    @driver.add_includes expected, []
+    @driver.add_from expected, @store
+    expected << @RM::Rule.new(1)
+
+    doc = @RM::Document.new(@RM::Paragraph.new('one'))
+    doc.file = 'one.rb'
+    expected.push doc
+    expected << @RM::BlankLine.new
+    doc = @RM::Document.new(@RM::Paragraph.new('two'))
+    doc.file = 'two.rb'
+    expected.push doc
+
+    expected << @RM::Rule.new(1)
+    expected << @RM::Heading.new(1, 'Instance methods:')
+    expected << @RM::BlankLine.new
+    expected << @RM::Verbatim.new('inherit')
+    expected << @RM::Verbatim.new('override')
+    expected << @RM::BlankLine.new
+
+    assert_equal expected, out
+  end
+
   def test_complete
     store = RDoc::RI::Store.new @home_ri
     store.cache[:ancestors] = {
@@ -633,8 +674,24 @@ Foo::Bar#bother
   def test_list_methods_matching
     util_store
 
-    assert_equal %w[Foo::Bar#attr Foo::Bar#blah Foo::Bar#bother Foo::Bar::new],
-                 @driver.list_methods_matching('Foo::Bar.')
+    assert_equal %w[
+        Foo::Bar#attr
+        Foo::Bar#blah
+        Foo::Bar#bother
+        Foo::Bar::new
+      ],
+      @driver.list_methods_matching('Foo::Bar.').sort
+  end
+
+  def test_list_methods_matching_inherit
+    util_multi_store
+
+    assert_equal %w[
+        Bar#baz
+        Bar#inherit
+        Bar#override
+      ],
+      @driver.list_methods_matching('Bar.').sort
   end
 
   def test_list_methods_matching_regexp
@@ -805,6 +862,42 @@ Foo::Bar#bother
     assert_equal 'baz',      meth,  'Foo::Bar#baz method'
   end
 
+  def test_parse_name_special
+    specials = %w[
+      %
+      &
+      *
+      +
+      +@
+      -
+      -@
+      /
+      <
+      <<
+      <=
+      <=>
+      ==
+      ===
+      =>
+      =~
+      >
+      >>
+      []
+      []=
+      ^
+      `
+      |
+      ~
+      ~@
+    ]
+
+    specials.each do |special|
+      parsed = @driver.parse_name special
+
+      assert_equal ['', '.', special], parsed
+    end
+  end
+
   def _test_setup_pager # this test doesn't do anything anymore :(
     @driver.use_stdout = false
 
@@ -864,29 +957,28 @@ Foo::Bar#bother
 
   def util_multi_store
     util_store
+
     @store1 = @store
 
+    @top_level = RDoc::TopLevel.new 'file.rb'
+
     @home_ri2 = "#{@home_ri}2"
     @store2 = RDoc::RI::Store.new @home_ri2
 
     # as if seen in a namespace like class Ambiguous::Other
-    @mAmbiguous = RDoc::NormalModule.new 'Ambiguous'
+    @mAmbiguous = @top_level.add_module RDoc::NormalModule, 'Ambiguous'
 
-    @cFoo = RDoc::NormalClass.new 'Foo'
+    @cFoo = @top_level.add_class RDoc::NormalClass, 'Foo'
 
-    @cBar = RDoc::NormalClass.new 'Bar'
-    @cBar.superclass = 'Foo'
-    @cFoo_Baz = RDoc::NormalClass.new 'Baz'
-    @cFoo_Baz.parent = @cFoo
+    @cBar = @top_level.add_class RDoc::NormalClass, 'Bar', 'Foo'
+    @cFoo_Baz = @cFoo.add_class RDoc::NormalClass, 'Baz'
 
-    @baz = RDoc::AnyMethod.new nil, 'baz'
+    @baz = @cBar.add_method RDoc::AnyMethod.new(nil, 'baz')
     @baz.record_location @top_level
-    @cBar.add_method @baz
 
-    @override = RDoc::AnyMethod.new nil, 'override'
+    @override = @cBar.add_method RDoc::AnyMethod.new(nil, 'override')
     @override.comment = 'must be displayed'
     @override.record_location @top_level
-    @cBar.add_method @override
 
     @store2.save_class @mAmbiguous
     @store2.save_class @cBar
@@ -898,6 +990,8 @@ Foo::Bar#bother
     @store2.save_cache
 
     @driver.stores = [@store1, @store2]
+
+    RDoc::RDoc.reset
   end
 
   def util_store
@@ -905,53 +999,42 @@ Foo::Bar#bother
 
     @top_level = RDoc::TopLevel.new 'file.rb'
 
-    @cFoo       = RDoc::NormalClass.new 'Foo'
-    @mInc       = RDoc::NormalModule.new 'Inc'
-    @cAmbiguous = RDoc::NormalClass.new 'Ambiguous'
+    @cFoo = @top_level.add_class RDoc::NormalClass, 'Foo'
+    @mInc = @top_level.add_module RDoc::NormalModule, 'Inc'
+    @cAmbiguous = @top_level.add_class RDoc::NormalClass, 'Ambiguous'
 
     doc = @RM::Document.new @RM::Paragraph.new('Include thingy')
-
-    @cFooInc = RDoc::Include.new 'Inc', doc
+    @cFooInc = @cFoo.add_include RDoc::Include.new('Inc', doc)
     @cFooInc.record_location @top_level
-    @cFoo.add_include @cFooInc
 
-    @cFoo_Bar = RDoc::NormalClass.new 'Bar'
-    @cFoo_Bar.parent = @cFoo
+    @cFoo_Bar = @cFoo.add_class RDoc::NormalClass, 'Bar'
 
-    @blah = RDoc::AnyMethod.new nil, 'blah'
+    @blah = @cFoo_Bar.add_method RDoc::AnyMethod.new(nil, 'blah')
     @blah.call_seq = "blah(5) => 5\nblah(6) => 6\n"
     @blah.record_location @top_level
 
-    @bother = RDoc::AnyMethod.new nil, 'bother'
+    @bother = @cFoo_Bar.add_method RDoc::AnyMethod.new(nil, 'bother')
     @bother.block_params = "stuff"
     @bother.params = "(things)"
     @bother.record_location @top_level
 
-    @new  = RDoc::AnyMethod.new nil, 'new'
+    @new = @cFoo_Bar.add_method RDoc::AnyMethod.new nil, 'new'
     @new.record_location @top_level
     @new.singleton = true
 
-    @cFoo_Bar.add_method @blah
-    @cFoo_Bar.add_method @bother
-    @cFoo_Bar.add_method @new
-
-    @attr = RDoc::Attr.new nil, 'attr', 'RW', ''
+    @attr = @cFoo_Bar.add_attribute RDoc::Attr.new nil, 'attr', 'RW', ''
     @attr.record_location @top_level
 
-    @cFoo_Bar.add_attribute @attr
+    @cFoo_Baz = @cFoo.add_class RDoc::NormalClass, 'Baz'
+    @cFoo_Baz.record_location @top_level
 
-    @cFoo_Baz = RDoc::NormalClass.new 'Baz'
-    @cFoo_Baz.parent = @cFoo
-
-    @inherit = RDoc::AnyMethod.new nil, 'inherit'
+    @inherit = @cFoo.add_method RDoc::AnyMethod.new(nil, 'inherit')
     @inherit.record_location @top_level
-    @cFoo.add_method @inherit
 
     # overriden by Bar in multi_store
-    @overriden = RDoc::AnyMethod.new nil, 'override'
+    @overriden = @cFoo.add_method RDoc::AnyMethod.new(nil, 'override')
     @overriden.comment = 'must not be displayed'
     @overriden.record_location @top_level
-    @cFoo.add_method @overriden
 
     @store.save_class @cFoo
     @store.save_class @cFoo_Bar
@@ -970,6 +1053,8 @@ Foo::Bar#bother
     @store.save_cache
 
     @driver.stores = [@store]
+
+    RDoc::RDoc.reset
   end
 
 end

test/rdoc/xref_test_case.rb

@@ -43,6 +43,11 @@ class XrefTestCase < MiniTest::Unit::TestCase
     @c2_b  = @c2.method_list.first
 
     @c2_c3 = @xref_data.find_module_named 'C2::C3'
+    @c2_c3_m = @c2_c3.method_list.first # C2::C3#m
+
+    @c2_c3_h1 = @xref_data.find_module_named 'C2::C3::H1'
+    @c2_c3_h1_meh = @c2_c3_h1.method_list.first # C2::C3::H1#m?
+
     @c3    = @xref_data.find_module_named 'C3'
     @c4    = @xref_data.find_module_named 'C4'
     @c4_c4 = @xref_data.find_module_named 'C4::C4'