rdoc 2.5.11 → 3.0

data/lib/rdoc/parser/ruby_tools.rb

@@ -49,7 +49,6 @@ module RDoc::Parser::RubyTools
           obj.pop_token
         end if @token_listeners
       else
-        warn("':' not followed by identifier or operator")
         tk = tk1
       end
     end
@@ -62,6 +61,10 @@ module RDoc::Parser::RubyTools
     tk
   end
 
+  ##
+  # Reads and returns all tokens up to one of +tokens+.  Leaves the matched
+  # token in the token list.
+
   def get_tk_until(*tokens)
     read = []
 

data/lib/rdoc/parser/simple.rb

@@ -1,7 +1,6 @@
 ##
 # Parse a non-source file. We basically take the whole thing as one big
-# comment. If the first character in the file is '#', we strip leading pound
-# signs.
+# comment.
 
 class RDoc::Parser::Simple < RDoc::Parser
 
@@ -32,10 +31,16 @@ class RDoc::Parser::Simple < RDoc::Parser
     @top_level
   end
 
-  def remove_private_comments(comment)
-    comment.gsub(/^--\n.*?^\+\+/m, '').sub(/^--\n.*/m, '')
+  ##
+  # Removes comments wrapped in <tt>--/++</tt>
+
+  def remove_private_comments text
+    text.gsub(/^--\n.*?^\+\+/m, '').sub(/^--\n.*/m, '')
   end
 
+  ##
+  # Removes the encoding magic comment from +text+
+
   def remove_coding_comment text
     text.sub(/\A# .*coding[=:].*$/, '')
   end

data/lib/rdoc/rdoc.rb

@@ -1,5 +1,6 @@
 require 'rdoc'
 
+require 'rdoc/encoding'
 require 'rdoc/parser'
 
 # Simple must come first
@@ -23,7 +24,28 @@ require 'time'
 #   rdoc.document(args)
 #
 # Where +args+ is an array of strings, each corresponding to an argument you'd
-# give rdoc on the command line. See rdoc/rdoc.rb for details.
+# give rdoc on the command line.  See <tt>rdoc --help<tt> for details.
+#
+# = Plugins
+#
+# When you <tt>require 'rdoc/rdoc'</tt> RDoc looks for 'rdoc/discover' files
+# in your installed gems.  This can be used to load alternate generators or
+# add additional preprocessor directives.
+#
+# You will want to wrap your plugin loading in an RDoc version check.
+# Something like:
+#
+#   begin
+#     gem 'rdoc', '~> 3'
+#     require 'path/to/my/awesome/rdoc/plugin'
+#   rescue Gem::LoadError
+#   end
+#
+# The most obvious plugin type is a new output generator.  See RDoc::Generator
+# for details.
+#
+# You can also hook into RDoc::Markup to add new directives (:nodoc: is a
+# directive).  See RDoc::Markup::PreProcess::register for details.
 
 class RDoc::RDoc
 
@@ -79,6 +101,10 @@ class RDoc::RDoc
     @current = rdoc
   end
 
+  ##
+  # Creates a new RDoc::RDoc instance.  Call #document to parse files and
+  # generate documentation.
+
   def initialize
     @current       = nil
     @exclude       = nil
@@ -142,7 +168,9 @@ class RDoc::RDoc
 
     last = {}
 
-    if File.exist? dir then
+    if @options.dry_run then
+      # do nothing
+    elsif File.exist? dir then
       error "#{dir} exists and is not a directory" unless File.directory? dir
 
       begin
@@ -167,7 +195,7 @@ you'll need to specify a different output directory name (using the --op <dir>
 option)
 
         ERROR
-      end
+      end unless @options.force_output
     else
       FileUtils.mkdir_p dir
     end
@@ -179,6 +207,8 @@ option)
   # Update the flag file in an output directory.
 
   def update_output_dir(op_dir, time, last = {})
+    return if @options.dry_run
+
     open output_flag_file(op_dir), "w" do |f|
       f.puts time.rfc2822
       last.each do |n, t|
@@ -277,7 +307,9 @@ option)
 
   def parse_file filename
     @stats.add_file filename
-    content = read_file_contents filename
+    encoding = @options.encoding if defined?(Encoding)
+
+    content = RDoc::Encoding.read_file filename, encoding
 
     return unless content
 
@@ -288,11 +320,22 @@ option)
     return unless parser
 
     parser.scan
+
+    # restart documentation for the classes & modules found
+    top_level.classes_or_modules.each do |cm|
+      cm.done_documenting = false
+    end
+
+    top_level
+
   rescue => e
     $stderr.puts <<-EOF
 Before reporting this, could you check that the file you're documenting
-compiles cleanly--RDoc is not a full Ruby parser, and gets confused easily if
-fed invalid programs.
+has proper syntax:
+
+  #{Gem.ruby} -c #{filename}
+
+RDoc is not a full Ruby parser and will fail when fed invalid ruby programs.
 
 The internal error was:
 
@@ -300,7 +343,7 @@ The internal error was:
 
     EOF
 
-    $stderr.puts e.backtrace.join("\n\t") if $RDOC_DEBUG
+    $stderr.puts e.backtrace.join("\n\t") if $DEBUG_RDOC
 
     raise e
     nil
@@ -344,11 +387,9 @@ The internal error was:
   # For simplicity, +argv+ is an array of strings, equivalent to the strings
   # that would be passed on the command line. (This isn't a coincidence, as
   # we _do_ pass in ARGV when running interactively). For a list of options,
-  # see rdoc/rdoc.rb. By default, output will be stored in a directory
+  # see <tt>rdoc --help</tt>. By default, output will be stored in a directory
   # called +doc+ below the current directory, so make sure you're somewhere
   # writable before invoking.
-  #
-  # Throws: RDoc::Error on error
 
   def document(argv)
     RDoc::TopLevel.reset
@@ -364,31 +405,36 @@ The internal error was:
 
     @exclude = @options.exclude
 
-    @last_modified = setup_output_dir @options.op_dir, @options.force_update
+    unless @options.coverage_report then
+      @last_modified = setup_output_dir @options.op_dir, @options.force_update
+    end
 
     start_time = Time.now
 
     file_info = parse_files @options.files
 
-    @options.title = "RDoc Documentation"
+    @options.default_title = "RDoc Documentation"
+
+    RDoc::TopLevel.complete @options.visibility
 
-    if file_info.empty?
+    if @options.coverage_report then
+      puts
+      puts @stats.report
+    elsif file_info.empty?
       $stderr.puts "\nNo newer files." unless @options.quiet
     else
       gen_klass = @options.generator
 
-      unless @options.quiet then
-        $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')}..."
-      end
-
-      @generator = gen_klass.for @options
-
-      pwd = Dir.pwd
+      @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
@@ -399,16 +445,10 @@ The internal error was:
 
     unless @options.quiet or not @stats then
       puts
-      @stats.print
+      puts @stats.summary
     end
-  end
 
-  def read_file_contents(filename)
-    content = open filename, "rb" do |f| f.read end
-    RDoc::Parser.set_encoding(content)
-    content
-  rescue Errno::EISDIR, Errno::ENOENT
-    nil
+    exit @stats.fully_documented? if @options.coverage_report
   end
 
   ##

data/lib/rdoc/require.rb

@@ -16,6 +16,7 @@ class RDoc::Require < RDoc::CodeObject
   def initialize(name, comment)
     super()
     @name = name.gsub(/'|"/, "") #'
+    @top_level = nil
     self.comment = comment
   end
 
@@ -28,5 +29,25 @@ class RDoc::Require < RDoc::CodeObject
     ]
   end
 
+  def to_s # :nodoc:
+    "require #{name} in: #{parent}"
+  end
+
+  ##
+  # The RDoc::TopLevel corresponding to this require, or +nil+ if not found.
+
+  def top_level
+    @top_level ||= begin
+      tl = RDoc::TopLevel.all_files_hash[name + '.rb']
+
+      if tl.nil? and RDoc::TopLevel.all_files.first.full_name =~ %r(^lib/) then
+        # second chance
+        tl = RDoc::TopLevel.all_files_hash['lib/' + name + '.rb']
+      end
+
+      tl
+    end
+  end
+
 end
 

data/lib/rdoc/ri/driver.rb

@@ -6,6 +6,11 @@ begin
 rescue LoadError
 end
 
+begin
+  require 'win32console'
+rescue LoadError
+end
+
 require 'rdoc/ri'
 require 'rdoc/ri/paths'
 require 'rdoc/markup'
@@ -55,6 +60,9 @@ class RDoc::RI::Driver
     end
   end
 
+  ##
+  # An RDoc::RI::Store for each entry in the RI path
+
   attr_accessor :stores
 
   ##
@@ -120,7 +128,7 @@ Where name can be:
 All class names may be abbreviated to their minimum unambiguous form. If a name
 is ambiguous, all valid options will be listed.
 
-The form '.' method matches either class or instance methods, while #method
+A '.' matches either class or instance methods, while #method
 matches only instance and ::method matches only class methods.
 
 For example:
@@ -130,7 +138,7 @@ For example:
     #{opt.program_name} File.new
     #{opt.program_name} zip
 
-Note that shell quoting may be required for method names containing
+Note that shell quoting or escaping may be required for method names containing
 punctuation:
 
     #{opt.program_name} 'Array.[]'
@@ -354,7 +362,7 @@ Options may also be set in the 'RI' environment variable.
 
     paths = RDoc::Markup::Verbatim.new
     also_in.each do |store|
-      paths.parts.push '  ', store.friendly_path, "\n"
+      paths.parts.push store.friendly_path, "\n"
     end
     out << paths
   end
@@ -422,7 +430,7 @@ Options may also be set in the 'RI' environment variable.
           verb = RDoc::Markup::Verbatim.new
 
           wout.each do |incl|
-            verb.push '  ', incl.name, "\n"
+            verb.push incl.name, "\n"
           end
 
           out << verb
@@ -441,7 +449,7 @@ Options may also be set in the 'RI' environment variable.
     out << RDoc::Markup::BlankLine.new
 
     out.push(*methods.map do |method|
-      RDoc::Markup::Verbatim.new '  ', method
+      RDoc::Markup::Verbatim.new method
     end)
 
     out << RDoc::Markup::BlankLine.new
@@ -546,7 +554,7 @@ Options may also be set in the 'RI' environment variable.
 
   def display document
     page do |io|
-      text = document.accept formatter
+      text = document.accept formatter(io)
 
       io.write text
     end
@@ -659,8 +667,8 @@ Options may also be set in the 'RI' environment variable.
 
         if method.arglists then
           arglists = method.arglists.chomp.split "\n"
-          arglists = arglists.map { |line| ['  ', line, "\n"] }
-          out << RDoc::Markup::Verbatim.new(*arglists.flatten)
+          arglists = arglists.map { |line| line + "\n" }
+          out << RDoc::Markup::Verbatim.new(*arglists)
           out << RDoc::Markup::Rule.new(1)
         end
 
@@ -795,10 +803,10 @@ Options may also be set in the 'RI' environment variable.
   # Creates a new RDoc::Markup::Formatter.  If a formatter is given with -f,
   # use it.  If we're outputting to a pager, use bs, otherwise ansi.
 
-  def formatter
+  def formatter(io)
     if @formatter_klass then
       @formatter_klass.new
-    elsif paging? then
+    elsif paging? or !io.tty? then
       RDoc::Markup::ToBs.new
     else
       RDoc::Markup::ToAnsi.new
@@ -1045,6 +1053,8 @@ Options may also be set in the 'RI' environment variable.
     pagers = [ENV['RI_PAGER'], ENV['PAGER'], 'pager', 'less', 'more']
 
     pagers.compact.uniq.each do |pager|
+      next unless pager
+
       pager_cmd = pager.split.first
 
       next unless in_path? pager_cmd

data/lib/rdoc/ri/paths.rb

@@ -37,7 +37,7 @@ module RDoc::RI::Paths
   #           true
   # :site:: Where ri for installed libraries are stored.  Yielded when
   #         +site+ is true.  Normally no ri data is stored here.
-  # :home:: ~/.ri.  Yielded when +home+ is true.
+  # :home:: ~/.rdoc.  Yielded when +home+ is true.
   # :gem:: ri data for an installed gem.  Yielded when +gems+ is true.
   # :extra:: ri data directory from the command line.  Yielded for each
   #          entry in +extra_dirs+
@@ -49,7 +49,7 @@ module RDoc::RI::Paths
 
     yield SYSDIR,  :system if system
     yield SITEDIR, :site   if site
-    yield HOMEDIR, :home   if home
+    yield HOMEDIR, :home   if home and HOMEDIR
 
     gemdirs.each do |dir|
       yield dir, :gem

data/lib/rdoc/ri/store.rb

@@ -10,6 +10,11 @@ require 'fileutils'
 
 class RDoc::RI::Store
 
+  ##
+  # If true this Store will not write any files
+
+  attr_accessor :dry_run
+
   ##
   # Path this store reads or writes
 
@@ -21,14 +26,18 @@ class RDoc::RI::Store
 
   attr_accessor :type
 
+  ##
+  # The contents of the Store
+
   attr_reader :cache
 
   ##
   # Creates a new Store of +type+ that will load or save to +path+
 
   def initialize path, type = nil
-    @type = type
-    @path = path
+    @dry_run = false
+    @type    = type
+    @path    = path
 
     @cache = {
       :class_methods    => {},
@@ -172,9 +181,13 @@ class RDoc::RI::Store
 
   def save_cache
     # HACK mongrel-1.1.5 documents its files twice
+    @cache[:ancestors].       each do |_, m| m.uniq!; m.sort! end
     @cache[:attributes].      each do |_, m| m.uniq!; m.sort! end
     @cache[:class_methods].   each do |_, m| m.uniq!; m.sort! end
     @cache[:instance_methods].each do |_, m| m.uniq!; m.sort! end
+    @cache[:modules].uniq!; @cache[:modules].sort!
+
+    return if @dry_run
 
     open cache_path, 'wb' do |io|
       Marshal.dump @cache, io
@@ -185,7 +198,7 @@ class RDoc::RI::Store
   # Writes the ri data for +klass+
 
   def save_class klass
-    FileUtils.mkdir_p class_path(klass.full_name)
+    FileUtils.mkdir_p class_path(klass.full_name) unless @dry_run
 
     @cache[:modules] << klass.full_name
 
@@ -212,7 +225,7 @@ class RDoc::RI::Store
     @cache[:ancestors][klass.full_name].push(*ancestors)
 
     attributes = klass.attributes.map do |attribute|
-      "#{attribute.type} #{attribute.name}"
+      "#{attribute.definition} #{attribute.name}"
     end
 
     unless attributes.empty? then
@@ -220,6 +233,8 @@ class RDoc::RI::Store
       @cache[:attributes][klass.full_name].push(*attributes)
     end
 
+    return if @dry_run
+
     open path, 'wb' do |io|
       Marshal.dump klass, io
     end
@@ -229,7 +244,7 @@ class RDoc::RI::Store
   # Writes the ri data for +method+ on +klass+
 
   def save_method klass, method
-    FileUtils.mkdir_p class_path(klass.full_name)
+    FileUtils.mkdir_p class_path(klass.full_name) unless @dry_run
 
     cache = if method.singleton then
               @cache[:class_methods]
@@ -239,6 +254,8 @@ class RDoc::RI::Store
     cache[klass.full_name] ||= []
     cache[klass.full_name] << method.name
 
+    return if @dry_run
+
     open method_file(klass.full_name, method.full_name), 'wb' do |io|
       Marshal.dump method, io
     end