Import RDoc 2.2.1 r185

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

1 files changed, 67 insertions, 21 deletions

diff --git a/lib/rdoc/markup/to_html_crossref.rb b/lib/rdoc/markup/to_html_crossref.rb
index a6f29c5c2c..dc64b30da1 100644
--- a/lib/rdoc/markup/to_html_crossref.rb
+++ b/lib/rdoc/markup/to_html_crossref.rb
@@ -9,6 +9,68 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
   attr_accessor :context
 
+  # Regular expressions to match class and method references.
+  # 
+  # 1.) There can be a '\' in front of text to suppress
+  #     any cross-references (note, however, that the single '\'
+  #     is written as '\\\\' in order to escape it twice, once
+  #     in the Ruby String literal and once in the regexp).
+  # 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,
+  #     which may or may not have things inside (this
+  #     apparently is allowed for Fortran 95, but I also think that this
+  #     is a good idea for Ruby, as it is very reasonable to want to
+  #     reference a call with arguments).
+  #
+  # NOTE: In order to support Fortran 95 properly, the [A-Z] below
+  # should be changed to [A-Za-z].  This slows down rdoc significantly,
+  # however, and the Fortran 95 support is broken in any case due to
+  # the return in handle_special_CROSSREF if the token consists
+  # entirely of lowercase letters.
+  #
+  # The markup/cross-referencing engine needs a rewrite for
+  # Fortran 95 to be supported properly.
+  CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
+  METHOD_REGEXP_STR = '(\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 (proceeded by a #)
+                      | \\?\##{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-referece is a space or sentence
+                      # punctuation.
+                      | #{CLASS_REGEXP_STR}(?=[\s\)\.\?\!\,\;]|\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
+                      | \\[^\s]
+                      )/x
+
   ##
   # We need to record the html path of our caller so we can generate
   # correct relative paths for any hyperlinks that we find
@@ -17,18 +79,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     raise ArgumentError, 'from_path cannot be nil' if from_path.nil?
     super()
 
-    # class names, variable names, or instance variables
-    @markup.add_special(/(
-                           # A::B.meth(**) (for operator in Fortran95)
-                           \w+(::\w+)*[.\#]\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?
-                           # meth(**) (for operator in Fortran95)
-                         | \#\w+(\([.\w\*\/\+\-\=\<\>]+\))?
-                         | \b([A-Z]\w*(::\w+)*[.\#]\w+)  #    A::B.meth
-                         | \b([A-Z]\w+(::\w+)*)          #    A::B
-                         | \#\w+[!?=]?                   #    #meth_name
-                         | \\?\b\w+([_\/\.]+\w+)*[!?=]?  #    meth_name
-                         )/x,
-                        :CROSSREF)
+    @markup.add_special(CROSSREF_REGEXP, :CROSSREF)
 
     @from_path = from_path
     @context = context
@@ -48,6 +99,9 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   def handle_special_CROSSREF(special)
     name = special.text
 
+    # This ensures that words entirely consisting of lowercase letters will
+    # not have cross-references generated (to suppress lots of
+    # erroneous cross-references to "new" in text, for instance)
     return name if name =~ /\A[a-z]*\z/
 
     return @seen[name] if @seen.include? name
@@ -70,14 +124,7 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
     # (in which case it would match the last pattern, which just checks
     # whether the string as a whole is a known symbol).
 
-    if /([A-Z][\w:]*)[.\#](\w+[!?=]?)/ =~ lookup then
-      container = $1
-      method = $2
-      ref = @context.find_symbol container, method
-    end
-
-    if !ref and
-       /([A-Za-z][\w:]*)[.\#](\w+(\([\.\w+\*\/\+\-\=\<\>]+\))?)/ =~ lookup then
+    if /#{CLASS_REGEXP_STR}[\.\#]#{METHOD_REGEXP_STR}/ =~ lookup then
       container = $1
       method = $2
       ref = @context.find_symbol container, method
@@ -99,4 +146,3 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   end
 
 end
-