rdoc 3.8 → 3.9

data/History.txt

@@ -1,4 +1,24 @@
-=== 3.8 / ??
+=== 3.9 / 2011-07-30
+
+* Minor enhancements
+  * RDoc::Parser::C now supports :doc: and :nodoc: for class comments
+  * Added the <tt>rdoc-ref:</tt> link scheme which links to a named reference.
+    <tt>rdoc-ref:</tt> can resolve references to classes, modules, methods,
+    files, etc.  This can be used to create cross-generator named links unlike
+    the <tt>link:</tt> scheme which is dependent upon the exact file name.
+    Issue #53 by Simon Chiang
+  * Pulled RDoc::CrossReference out of RDoc::Markup::ToHtmlCrossref.
+    Cross-references can now be created easily for non-HTML formatters.
+* Bug fixes
+  * `ri []` and other special methods now work properly.  Issue #52 by
+    ddebernardy.
+  * `ri` now has space between class comments from multiple files.
+  * :stopdoc: no longer creates Object references.  Issue #55 by Simon Chiang
+  * :nodoc: works on class aliases now.  Issue #51 by Steven G. Harms
+  * Remove tokenizer restriction on header lengths for verbatim sections.
+    Issue #49 by trans
+
+=== 3.8 / 2011-06-29
 
 * Minor enhancements
   * RDoc::Parser::C can now discover methods on ENV and ARGF.

data/Manifest.txt

@@ -18,6 +18,7 @@ lib/rdoc/code_object.rb
 lib/rdoc/code_objects.rb
 lib/rdoc/constant.rb
 lib/rdoc/context.rb
+lib/rdoc/cross_reference.rb
 lib/rdoc/encoding.rb
 lib/rdoc/erbio.rb
 lib/rdoc/gauntlet.rb
@@ -127,6 +128,7 @@ test/test_rdoc_code_object.rb
 test/test_rdoc_constant.rb
 test/test_rdoc_context.rb
 test/test_rdoc_context_section.rb
+test/test_rdoc_cross_reference.rb
 test/test_rdoc_encoding.rb
 test/test_rdoc_generator_darkfish.rb
 test/test_rdoc_generator_ri.rb

data/Rakefile

@@ -19,13 +19,27 @@ Hoe.spec 'rdoc' do
   rdoc_locations << 'docs.seattlerb.org:/data/www/docs.seattlerb.org/rdoc/'
   rdoc_locations << 'drbrain@rubyforge.org:/var/www/gforge-projects/rdoc/'
 
+
+  spec_extras[:post_install_message] = <<-MESSAGE
+Depending on your version of ruby, you may need to install ruby rdoc/ri data:
+
+<= 1.8.6 : unsupported
+ = 1.8.7 : gem install rdoc-data; rdoc-data --install
+ = 1.9.1 : gem install rdoc-data; rdoc-data --install
+>= 1.9.2 : nothing to do! Yay!
+  MESSAGE
+
   self.testlib = :minitest
-  self.isolate_dir = 'tmp/isolate'
+  if respond_to? :isolate_dir= then # HACK Hoe issue #7
+    self.isolate_dir = 'tmp/isolate'
+  else
+    warn 'please: gem install isolate'
+  end
 
   require_ruby_version '>= 1.8.7'
-  extra_dev_deps   << ['minitest', '~> 2']
-  extra_dev_deps   << ['isolate',  '~> 3']
-  extra_dev_deps   << ['ZenTest',  '~> 4'] # for autotest/isolate
+  extra_dev_deps << ['minitest', '~> 2']
+  extra_dev_deps << ['isolate',  '~> 3']
+  extra_dev_deps << ['ZenTest',  '~> 4'] # for autotest/isolate
 
   extra_rdoc_files << 'Rakefile'
   spec_extras['required_rubygems_version'] = '>= 1.3'

data/bin/rdoc

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

data/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

data/lib/rdoc.rb

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

data/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,

data/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
 
   ##

data/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)

data/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
+

data/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
 

data/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">

data/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