rdoc 3.5.3 → 3.6

data/History.txt

@@ -1,3 +1,28 @@
+=== 3.6 / 2011-05-13
+
+* Major Enhancements
+  * Interactive ri is now the default when no names are given.
+* Minor Enhancements
+  * RDoc::RDoc#generate was added to allow multiple generators to be used with
+    a set of parsed file info.
+  * RDoc::Options#finish can be called multiple times now.
+  * `ri -i` only shows one level of namespace when completing class names.
+  * Added `ri --list` for explicit listing.  `ri -l F G` will list all classes
+    or modules starting with F or G
+* Bug fixes
+  * Remove windows-specific test for test_check_files, it is too hard to do.
+    Ruby commit r30811 by Usaku Nakamura.
+  * Remove unnecessary (and wrong) platform-dependent hacks.  Ruby commit
+    r30829 by Usaku Nakamura.
+  * Completing via Array#[ in `ri -i` no longer crashes.  Ruby Bug #3167
+  * Completing IO::o in `ri -i` now returns results.  Ruby Bug #3167
+  * RDoc::Parser::C ignores prototypes better.  Pull Request #34 by Pete
+    Higgins.
+  * private_class_method and public_class_method are now parsed correctly for
+    inherited methods.  Issue #16 by gitsucks.
+  * The doc directive now forces documentation even when the method is marked
+    private or protected.
+
 === 3.5.3 / 2010-02-06
 
 * Bug fixes

data/README.txt

@@ -14,15 +14,31 @@ See RDoc for a description of RDoc's markup and basic use.
 
 == SYNOPSIS:
 
-To generate HTML documentation:
+To learn RDoc's syntax and directives for documenting your ruby project see
+RDoc::Markup.  RDoc::Parser::Ruby and RDoc::Parser::C have additional
+directives (such as metaprogrammed methods) for documenting Ruby and C files
+respectively.
 
-  rdoc .
+To generate HTML documentation for your project run <tt>rdoc .</tt> in your
+project's root directory.
+
+To determine how well your project is documented run <tt>rdoc -C lib</tt> to
+get a documentation coverage report.  <tt>rdoc -C1 lib</tt> includes parameter
+names in the documentation coverage report.
+
+To generate documentation using +rake+ see RDoc::Task.
 
 To generate documentation programmatically:
 
   gem 'rdoc'
   require 'rdoc/rdoc'
-  # ... see RDoc
+
+  options = RDoc::Options.new
+  # see RDoc::Options
+
+  rdoc = RDoc::RDoc.new
+  rdoc.document options
+  # see RDoc::RDoc
 
 == BUGS:
 

data/Rakefile

@@ -29,31 +29,7 @@ Hoe.spec 'rdoc' do
 
   extra_rdoc_files << 'Rakefile'
   spec_extras['required_rubygems_version'] = '>= 1.3'
-  spec_extras['homepage'] = 'http://rdoc.rubyforge.org'
-
-  spec_extras[:post_install_message] = <<-EOF
-NOTE: If you are running Ruby 1.9.2 you can ignore this message.
-
-RDoc 2.5+ has a new ri data format for Ruby 1.8.7 and 1.9.1.  (1.9.2 contains
-RDoc 2.5 so there is nothing to do!)
-
-To install new ri data for core and stdlib you'll need to:
-
-  gem install rdoc-data
-
-then run:
-
-  rdoc-data --install
-
-To have ri data for you gems you'll also need to run:
-
-  gem rdoc --all --overwrite
-
-If you don't want to rebuild the rdoc for `gem server`, add --no-rdoc.
-
-NOTE:  RDoc 2.5 did not save method parameters, so you should upgrade your
-rdoc-data gem to a version >= 2.5.3 if you installed an older version.
-  EOF
+  spec_extras['homepage'] = 'http://docs.seattlerb.org/rdoc'
 end
 
 # These tasks expect to have the following directory structure:

data/lib/rdoc.rb

@@ -3,31 +3,39 @@ $DEBUG_RDOC = nil
 # :main: README.txt
 
 ##
-# = \RDoc - Ruby Documentation System
-#
-# This package contains RDoc and RDoc::Markup.  RDoc is an application that
-# produces documentation for one or more Ruby source files.  It works similarly
-# to JavaDoc, parsing the source, and extracting the definition for classes,
-# modules, and methods (along with includes and requires).  It associates with
-# these optional documentation contained in the immediately preceding comment
-# block, and then renders the result using a pluggable output formatter.
-# RDoc::Markup is a library that converts plain text into various output
-# formats.  The markup library is used to interpret the comment blocks that
-# RDoc uses to document methods, classes, and so on.
+# RDoc is a Ruby documentation system which contains RDoc::RDoc for generating
+# documentation, RDoc::RI for interactive documentation and RDoc::Markup for
+# text markup.
+#
+# RDoc::RDoc produces documentation for Ruby source files.  It works similarly
+# to JavaDoc, parsing the source and extracting the definition for classes,
+# modules, methods, includes and requires.  It associates these with optional
+# documentation contained in an immediately preceding comment block then
+# renders the result using an output formatter.
+#
+# RDoc::Markup that converts plain text into various output formats.  The
+# markup library is used to interpret the comment blocks that RDoc uses to
+# document methods, classes, and so on.
+#
+# RDoc::RI implements the +ri+ command-line tool which displays on-line
+# documentation for ruby classes, methods, etc.  +ri+ features several output
+# formats and an interactive mode (<tt>ri -i</tt>).  See <tt>ri --help</tt>
+# for further details.
 #
 # == Roadmap
 #
 # * If you want to use RDoc to create documentation for your Ruby source files,
-#   read the summary below, and refer to <tt>rdoc --help</tt> for command line
-#   usage, and RDoc::Markup for a detailed description of RDoc's markup.
+#   see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line
+#   usage.
 # * If you want to generate documentation for extensions written in C, see
 #   RDoc::Parser::C
+# * If you want to generate documentation using <tt>rake</tt> see RDoc::Task.
 # * If you want to drive RDoc programmatically, see RDoc::RDoc.
 # * If you want to use the library to format text blocks into HTML, look at
 #   RDoc::Markup.
 # * If you want to make an RDoc plugin such as a generator or directive
 #   handler see RDoc::RDoc.
-# * If you want to try writing your own output generator see RDoc::Generator.
+# * If you want to write your own output generator see RDoc::Generator.
 #
 # == Summary
 #
@@ -95,7 +103,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '3.5.3'
+  VERSION = '3.6'
 
   ##
   # Method visibilities

data/lib/rdoc/attr.rb

@@ -68,6 +68,19 @@ class RDoc::Attr < RDoc::MethodAttr
     end
   end
 
+  def inspect # :nodoc:
+    alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
+    visibility = self.visibility
+    visibility = "forced #{visibility}" if force_documentation
+    "#<%s:0x%x %s %s (%s)%s>" % [
+      self.class, object_id,
+      full_name,
+      rw,
+      visibility,
+      alias_for,
+    ]
+  end
+
   ##
   # Dumps this Attr for use by ri.  See also #marshal_load
 

data/lib/rdoc/class_module.rb

@@ -137,12 +137,22 @@ class RDoc::ClassModule < RDoc::Context
     remove_invisible min_visibility
   end
 
+  ##
+  # Iterates the ancestors of this class or module for which an
+  # RDoc::ClassModule exists.
+
+  def each_ancestor # :yields: module
+    ancestors.each do |mod|
+      next if String === mod
+      yield mod
+    end
+  end
+
   ##
   # Looks for a symbol in the #ancestors. See Context#find_local_symbol.
 
   def find_ancestor_local_symbol symbol
-    ancestors.each do |m|
-      next if m.is_a?(String)
+    each_ancestor do |m|
       res = m.find_local_symbol(symbol)
       return res if res
     end
@@ -263,7 +273,7 @@ class RDoc::ClassModule < RDoc::Context
 
     class_module.each_attribute do |attr|
       if match = attributes.find { |a| a.name == attr.name } then
-        match.rw = [match.rw, attr.rw].compact.join
+        match.rw = [match.rw, attr.rw].compact.uniq.join
       else
         add_attribute attr
       end

data/lib/rdoc/code_object.rb

@@ -180,6 +180,20 @@ class RDoc::CodeObject
     @document_children = @document_self
   end
 
+  ##
+  # Yields each parent of this CodeObject.  See also
+  # RDoc::ClassModule#each_ancestor
+
+  def each_parent
+    code_object = self
+
+    while code_object = code_object.parent do
+      yield code_object
+    end
+
+    self
+  end
+
   ##
   # Force the documentation of this object unless documentation
   # has been turned off by :endoc:

data/lib/rdoc/context.rb

@@ -480,7 +480,7 @@ class RDoc::Context < RDoc::CodeObject
   # Adds included module +include+ which should be an RDoc::Include
 
   def add_include(include)
-    add_to @includes, include
+    add_to @includes, include unless @includes.map { |i| i.full_name }.include?( include.full_name )
   end
 
   ##
@@ -950,10 +950,14 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Yields AnyMethod and Attr entries matching the list of names in +methods+.
 
-  def methods_matching(methods, singleton = false)
+  def methods_matching(methods, singleton = false, &block)
     (@method_list + @attributes).each do |m|
       yield m if methods.include?(m.name) and m.singleton == singleton
     end
+
+    each_ancestor do |parent|
+      parent.methods_matching(methods, singleton, &block)
+    end
   end
 
   ##
@@ -1021,11 +1025,19 @@ class RDoc::Context < RDoc::CodeObject
     remove_invisible_in @attributes, min_visibility
   end
 
+  ##
+  # Only called when min_visibility == :public or :private
+
   def remove_invisible_in(array, min_visibility) # :nodoc:
     if min_visibility == :public
-      array.reject! { |e| e.visibility != :public }
+      array.reject! { |e|
+        e.visibility != :public and not e.force_documentation
+      }
     else
-      array.reject! { |e| e.visibility == :private }
+      array.reject! { |e|
+        e.visibility == :private and
+          not e.force_documentation
+      }
     end
   end
 

data/lib/rdoc/method_attr.rb

@@ -333,6 +333,8 @@ class RDoc::MethodAttr < RDoc::CodeObject
 
   def inspect # :nodoc:
     alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
+    visibility = self.visibility
+    visibility = "forced #{visibility}" if force_documentation
     "#<%s:0x%x %s (%s)%s>" % [
       self.class, object_id,
       full_name,

data/lib/rdoc/options.rb

@@ -256,7 +256,9 @@ class RDoc::Options
 
     @rdoc_include << "." if @rdoc_include.empty?
 
-    if @exclude.empty? then
+    if @exclude.nil? or Regexp === @exclude then
+      # done, #finish is being re-run
+    elsif @exclude.empty? then
       @exclude = nil
     else
       @exclude = Regexp.new(@exclude.join("|"))

data/lib/rdoc/parser/c.rb

@@ -376,7 +376,7 @@ class RDoc::Parser::C < RDoc::Parser
     when %r%((?>/\*.*?\*/\s*)?)
             ((?:(?:static|SWIGINTERN)\s+)?
              (?:intern\s+)?VALUE\s+#{meth_name}
-             \s*(\(.*?\))([^;]|$))%xm then
+             \s*(\([^)]*\))([^;]|$))%xm then
       comment = $1
       body = $2
       offset = $~.offset(2).first

data/lib/rdoc/parser/ruby.rb

@@ -1558,32 +1558,45 @@ class RDoc::Parser::Ruby < RDoc::Parser
     when TkNL, TkUNLESS_MOD, TkIF_MOD, TkSEMICOLON then
       container.ongoing_visibility = vis
     else
-      if vis_type == 'module_function' then
+      new_methods = []
+
+      case vis_type 
+      when 'module_function' then
         args = parse_symbol_arg
         container.set_visibility_for args, :private, false
 
-        module_functions = []
-
         container.methods_matching args do |m|
           s_m = m.dup
           s_m.record_location @top_level
           s_m.singleton = true
-          s_m.visibility = :public
-          module_functions << s_m
+          new_methods << s_m
         end
+      when 'public_class_method', 'private_class_method' then
+        args = parse_symbol_arg
 
-        module_functions.each do |s_m|
-          case s_m
-          when RDoc::AnyMethod then
-            container.add_method s_m
-          when RDoc::Attr then
-            container.add_attribute s_m
+        container.methods_matching args, true do |m|
+          if m.parent != container then
+            m = m.dup
+            m.record_location @top_level
+            new_methods << m
           end
+
+          m.visibility = vis
         end
       else
         args = parse_symbol_arg
         container.set_visibility_for args, vis, singleton
       end
+
+      new_methods.each do |method|
+        case method
+        when RDoc::AnyMethod then
+          container.add_method method
+        when RDoc::Attr then
+          container.add_attribute method
+        end
+        method.visibility = vis
+      end
     end
   end
 

data/lib/rdoc/rdoc.rb

@@ -418,7 +418,7 @@ The internal error was:
       @last_modified = setup_output_dir @options.op_dir, @options.force_update
     end
 
-    start_time = Time.now
+    @start_time = Time.now
 
     file_info = parse_files @options.files
 
@@ -439,23 +439,10 @@ The internal error was:
 
       @generator = gen_klass.new @options
 
-      Dir.chdir @options.op_dir do
-        begin
-          self.class.current = self
-
-          unless @options.quiet then
-            $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
-          end
-
-          @generator.generate file_info
-          update_output_dir ".", start_time, @last_modified
-        ensure
-          self.class.current = nil
-        end
-      end
+      generate file_info
     end
 
-    unless @options.quiet or not @stats then
+    if @stats and (@options.coverage_report or not @options.quiet) then
       puts
       puts @stats.summary
     end
@@ -463,6 +450,28 @@ The internal error was:
     exit @stats.fully_documented? if @options.coverage_report
   end
 
+  ##
+  # Generates documentation for +file_info+ (from #parse_files) into the
+  # output dir using the generator selected
+  # by the RDoc options
+
+  def generate file_info
+    Dir.chdir @options.op_dir do
+      begin
+        self.class.current = self
+
+        unless @options.quiet then
+          $stderr.puts "\nGenerating #{@generator.class.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
+        end
+
+        @generator.generate file_info
+        update_output_dir '.', @start_time, @last_modified
+      ensure
+        self.class.current = nil
+      end
+    end
+  end
+
   ##
   # Removes a siginfo handler and replaces the previous
 

data/lib/rdoc/ri/driver.rb

@@ -197,6 +197,13 @@ Options may also be set in the 'RI' environment variable.
 
       opt.separator nil
 
+      opt.on("--list", "-l",
+             "List classes ri knows about.") do
+        options[:list] = true
+      end
+
+      opt.separator nil
+
       opt.on("--[no-]profile",
              "Run with the ruby profiler") do |value|
         options[:profile] = value
@@ -331,6 +338,7 @@ Options may also be set in the 'RI' environment variable.
     require 'profile' if options[:profile]
 
     @names = options[:names]
+    @list = options[:list]
 
     @doc_dirs = []
     @stores   = []
@@ -524,7 +532,10 @@ Options may also be set in the 'RI' environment variable.
     klass_name = method ? name : klass
 
     if name !~ /#|\./ then
-      completions.push(*klasses.grep(/^#{klass_name}/))
+      completions = klasses.grep(/^#{klass_name}[^:]*$/)
+      completions.concat klasses.grep(/^#{name}[^:]*$/) if name =~ /::$/
+
+      completions << klass if classes.key? klass # to complete a method name
     elsif selector then
       completions << klass if classes.key? klass
     elsif classes.key? klass_name then
@@ -546,7 +557,7 @@ Options may also be set in the 'RI' environment variable.
       completions.push(*methods)
     end
 
-    completions.sort
+    completions.sort.uniq
   end
 
   ##
@@ -878,9 +889,10 @@ Options may also be set in the 'RI' environment variable.
   end
 
   ##
-  # Lists classes known to ri
+  # Lists classes known to ri starting with +names+.  If +names+ is empty all
+  # known classes are shown.
 
-  def list_known_classes
+  def list_known_classes names = []
     classes = []
 
     stores.each do |store|
@@ -889,9 +901,19 @@ Options may also be set in the 'RI' environment variable.
 
     classes = classes.flatten.uniq.sort
 
+    unless names.empty? then
+      filter = Regexp.union names.map { |name| /^#{name}/ }
+
+      classes = classes.grep filter
+    end
+
     page do |io|
       if paging? or io.tty? then
-        io.puts "Classes and Modules known to ri:"
+        if names.empty? then
+          io.puts "Classes and Modules known to ri:"
+        else
+          io.puts "Classes and Modules starting with #{names.join ', '}:"
+        end
         io.puts
       end
 
@@ -910,7 +932,7 @@ Options may also be set in the 'RI' environment variable.
         methods = store.instance_methods[ancestor]
 
         if methods then
-          matches = methods.grep(/^#{method}/)
+          matches = methods.grep(/^#{Regexp.escape method.to_s}/)
 
           matches = matches.map do |match|
             "#{klass}##{match}"
@@ -924,7 +946,7 @@ Options may also be set in the 'RI' environment variable.
         methods = store.class_methods[ancestor]
 
         next unless methods
-        matches = methods.grep(/^#{method}/)
+        matches = methods.grep(/^#{Regexp.escape method.to_s}/)
 
         matches = matches.map do |match|
           "#{klass}::#{match}"
@@ -996,9 +1018,9 @@ Options may also be set in the 'RI' environment variable.
 
     case type
     when '#', '::' then
-      /^#{klass}#{type}#{name}$/
+      /^#{klass}#{type}#{Regexp.escape name}$/
     else
-      /^#{klass}(#|::)#{name}$/
+      /^#{klass}(#|::)#{Regexp.escape name}$/
     end
   end
 
@@ -1064,10 +1086,10 @@ Options may also be set in the 'RI' environment variable.
   def run
     if @list_doc_dirs then
       puts @doc_dirs
-    elsif @interactive then
+    elsif @list then
+      list_known_classes @names
+    elsif @interactive or @names.empty? then
       interactive
-    elsif @names.empty? then
-      list_known_classes
     else
       display_names @names
     end