rdoc 3.1 → 6.3.3

data/lib/rdoc/rdoc.rb

@@ -1,57 +1,39 @@
+# frozen_string_literal: true
 require 'rdoc'
 
-require 'rdoc/encoding'
-require 'rdoc/parser'
-
-# Simple must come first
-require 'rdoc/parser/simple'
-require 'rdoc/parser/ruby'
-require 'rdoc/parser/c'
-
-require 'rdoc/stats'
-require 'rdoc/options'
-
 require 'find'
 require 'fileutils'
+require 'pathname'
 require 'time'
 
 ##
-# Encapsulate the production of rdoc documentation. Basically you can use this
-# as you would invoke rdoc from the command line:
-#
-#   rdoc = RDoc::RDoc.new
-#   rdoc.document(args)
+# This is the driver for generating RDoc output.  It handles file parsing and
+# generation of output.
 #
-# Where +args+ is an array of strings, each corresponding to an argument you'd
-# give rdoc on the command line.  See <tt>rdoc --help<tt> for details.
+# To use this class to generate RDoc output via the API, the recommended way
+# is:
 #
-# = 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:
+#   rdoc = RDoc::RDoc.new
+#   options = rdoc.load_options # returns an RDoc::Options instance
+#   # set extra options
+#   rdoc.document options
 #
-#   begin
-#     gem 'rdoc', '~> 3'
-#     require 'path/to/my/awesome/rdoc/plugin'
-#   rescue Gem::LoadError
-#   end
+# You can also generate output like the +rdoc+ executable:
 #
-# The most obvious plugin type is a new output generator.  See RDoc::Generator
-# for details.
+#   rdoc = RDoc::RDoc.new
+#   rdoc.document argv
 #
-# You can also hook into RDoc::Markup to add new directives (:nodoc: is a
-# directive).  See RDoc::Markup::PreProcess::register for details.
+# Where +argv+ is an array of strings, each corresponding to an argument you'd
+# give rdoc on the command line.  See <tt>rdoc --help</tt> for details.
 
 class RDoc::RDoc
 
+  @current = nil
+
   ##
-  # File pattern to exclude
+  # This is the list of supported output generators
 
-  attr_accessor :exclude
+  GENERATORS = {}
 
   ##
   # Generator instance used for creating output
@@ -74,9 +56,9 @@ class RDoc::RDoc
   attr_reader :stats
 
   ##
-  # This is the list of supported output generators
+  # The current documentation store
 
-  GENERATORS = {}
+  attr_reader :store
 
   ##
   # Add +klass+ that can generate output after parsing
@@ -96,7 +78,7 @@ class RDoc::RDoc
   ##
   # Sets the active RDoc::RDoc instance
 
-  def self.current=(rdoc)
+  def self.current= rdoc
     @current = rdoc
   end
 
@@ -106,12 +88,12 @@ class RDoc::RDoc
 
   def initialize
     @current       = nil
-    @exclude       = nil
     @generator     = nil
     @last_modified = {}
     @old_siginfo   = nil
     @options       = nil
     @stats         = nil
+    @store         = nil
   end
 
   ##
@@ -128,20 +110,32 @@ class RDoc::RDoc
   def gather_files files
     files = ["."] if files.empty?
 
-    file_list = normalized_file_list files, true, @exclude
+    file_list = normalized_file_list files, true, @options.exclude
 
-    file_list = file_list.uniq
+    file_list = remove_unparseable(file_list)
 
-    file_list = remove_unparseable file_list
+    if file_list.count {|name, mtime|
+         file_list[name] = @last_modified[name] unless mtime
+         mtime
+       } > 0
+      @last_modified.replace file_list
+      file_list.keys.sort
+    else
+      []
+    end
   end
 
   ##
   # Turns RDoc from stdin into HTML
 
   def handle_pipe
-    @html = RDoc::Markup::ToHtml.new
+    @html = RDoc::Markup::ToHtml.new @options
+
+    parser = RDoc::Text::MARKUP_FORMAT[@options.markup]
 
-    out = @html.convert $stdin.read
+    document = parser.parse $stdin.read
+
+    out = @html.convert document
 
     $stdout.write out
   end
@@ -157,6 +151,34 @@ class RDoc::RDoc
     end
   end
 
+  ##
+  # Loads options from .rdoc_options if the file exists, otherwise creates a
+  # new RDoc::Options instance.
+
+  def load_options
+    options_file = File.expand_path '.rdoc_options'
+    return RDoc::Options.new unless File.exist? options_file
+
+    RDoc.load_yaml
+
+    begin
+      options = YAML.load_file '.rdoc_options'
+    rescue Psych::SyntaxError
+    end
+
+    return RDoc::Options.new if options == false # Allow empty file.
+
+    raise RDoc::Error, "#{options_file} is not a valid rdoc options file" unless
+      RDoc::Options === options or Hash === options
+
+    if Hash === options
+      # Override the default values with the contents of YAML file.
+      options = RDoc::Options.new options
+    end
+
+    options
+  end
+
   ##
   # Create an output dir if it doesn't exist. If it does exist, but doesn't
   # contain the flag file <tt>created.rid</tt> then we refuse to use it, as
@@ -173,7 +195,7 @@ class RDoc::RDoc
       error "#{dir} exists and is not a directory" unless File.directory? dir
 
       begin
-        open flag_file do |io|
+        File.open flag_file do |io|
           unless force then
             Time.parse io.gets
 
@@ -197,18 +219,31 @@ option)
       end unless @options.force_output
     else
       FileUtils.mkdir_p dir
+      FileUtils.touch flag_file
     end
 
     last
   end
 
+  ##
+  # Sets the current documentation tree to +store+ and sets the store's rdoc
+  # driver to this instance.
+
+  def store= store
+    @store = store
+    @store.rdoc = self
+  end
+
   ##
   # Update the flag file in an output directory.
 
   def update_output_dir(op_dir, time, last = {})
-    return if @options.dry_run
+    return if @options.dry_run or not @options.update_output_dir
+    unless ENV['SOURCE_DATE_EPOCH'].nil?
+      time = Time.at(ENV['SOURCE_DATE_EPOCH'].to_i).gmtime
+    end
 
-    open output_flag_file(op_dir), "w" do |f|
+    File.open output_flag_file(op_dir), "w" do |f|
       f.puts time.rfc2822
       last.each do |n, t|
         f.puts "#{n}\t#{t.rfc2822}"
@@ -232,11 +267,11 @@ option)
     # read and strip comments
     patterns = File.read(filename).gsub(/#.*/, '')
 
-    result = []
+    result = {}
 
-    patterns.split.each do |patt|
+    patterns.split(' ').each do |patt|
       candidates = Dir.glob(File.join(in_dir, patt))
-      result.concat normalized_file_list(candidates)
+      result.update normalized_file_list(candidates, false, @options.exclude)
     end
 
     result
@@ -256,37 +291,41 @@ option)
 
   def normalized_file_list(relative_files, force_doc = false,
                            exclude_pattern = nil)
-    file_list = []
+    file_list = {}
 
     relative_files.each do |rel_file_name|
+      rel_file_name = rel_file_name.sub(/^\.\//, '')
+      next if rel_file_name.end_with? 'created.rid'
       next if exclude_pattern && exclude_pattern =~ rel_file_name
       stat = File.stat rel_file_name rescue next
 
       case type = stat.ftype
       when "file" then
-        next if last_modified = @last_modified[rel_file_name] and
-                stat.mtime.to_i <= last_modified.to_i
+        mtime = (stat.mtime unless (last_modified = @last_modified[rel_file_name] and
+                                    stat.mtime.to_i <= last_modified.to_i))
 
         if force_doc or RDoc::Parser.can_parse(rel_file_name) then
-          file_list << rel_file_name.sub(/^\.\//, '')
-          @last_modified[rel_file_name] = stat.mtime
+          file_list[rel_file_name] = mtime
         end
       when "directory" then
         next if rel_file_name == "CVS" || rel_file_name == ".svn"
 
+        created_rid = File.join rel_file_name, "created.rid"
+        next if File.file? created_rid
+
         dot_doc = File.join rel_file_name, RDoc::DOT_DOC_FILENAME
 
         if File.file? dot_doc then
-          file_list << parse_dot_doc_file(rel_file_name, dot_doc)
+          file_list.update(parse_dot_doc_file(rel_file_name, dot_doc))
         else
-          file_list << list_files_in_directory(rel_file_name)
+          file_list.update(list_files_in_directory(rel_file_name))
         end
       else
-        raise RDoc::Error, "I can't deal with a #{type} #{rel_file_name}"
+        warn "rdoc can't parse the #{type} #{rel_file_name}"
       end
     end
 
-    file_list.flatten
+    file_list
   end
 
   ##
@@ -305,14 +344,31 @@ option)
   # Parses +filename+ and returns an RDoc::TopLevel
 
   def parse_file filename
+    encoding = @options.encoding
+    filename = filename.encode encoding
+
     @stats.add_file filename
-    encoding = @options.encoding if defined?(Encoding)
+
+    return if RDoc::Parser.binary? filename
 
     content = RDoc::Encoding.read_file filename, encoding
 
     return unless content
 
-    top_level = RDoc::TopLevel.new filename
+    filename_path = Pathname(filename).expand_path
+    begin
+      relative_path = filename_path.relative_path_from @options.root
+    rescue ArgumentError
+      relative_path = filename_path
+    end
+
+    if @options.page_dir and
+       relative_path.to_s.start_with? @options.page_dir.to_s then
+      relative_path =
+        relative_path.relative_path_from @options.page_dir
+    end
+
+    top_level = @store.add_file filename, relative_name: relative_path.to_s
 
     parser = RDoc::Parser.for top_level, filename, content, @options, @stats
 
@@ -327,6 +383,14 @@ option)
 
     top_level
 
+  rescue Errno::EACCES => e
+    $stderr.puts <<-EOF
+Unable to read #{filename}, #{e.message}
+
+Please check the permissions for this file.  Perhaps you do not have access to
+it or perhaps the original author's permissions are to restrictive.  If the
+this is not your library please report a bug to the author.
+    EOF
   rescue => e
     $stderr.puts <<-EOF
 Before reporting this, could you check that the file you're documenting
@@ -353,12 +417,11 @@ The internal error was:
 
   def parse_files files
     file_list = gather_files files
+    @stats = RDoc::Stats.new @store, file_list.length, @options.verbosity
 
     return [] if file_list.empty?
 
-    file_info = []
-
-    @stats = RDoc::Stats.new file_list.size, @options.verbosity
+    original_options = @options.dup
     @stats.begin_adding
 
     file_info = file_list.map do |filename|
@@ -367,89 +430,120 @@ The internal error was:
     end.compact
 
     @stats.done_adding
+    @options = original_options
 
     file_info
   end
 
   ##
-  # Removes file extensions known to be unparseable from +files+
+  # Removes file extensions known to be unparseable from +files+ and TAGS
+  # files for emacs and vim.
 
   def remove_unparseable files
-    files.reject do |file|
-      file =~ /\.(?:class|eps|erb|scpt\.txt|ttf|yml)$/i
+    files.reject do |file, *|
+      file =~ /\.(?:class|eps|erb|scpt\.txt|svg|ttf|yml)$/i or
+        (file =~ /tags$/i and
+         File.open(file, 'rb') { |io|
+           io.read(100) =~ /\A(\f\n[^,]+,\d+$|!_TAG_)/
+         })
     end
   end
 
   ##
-  # Format up one or more files according to the given arguments.
+  # Generates documentation or a coverage report depending upon the settings
+  # in +options+.
+  #
+  # +options+ can be either an RDoc::Options instance or an array of strings
+  # equivalent to the strings that would be passed on the command line like
+  # <tt>%w[-q -o doc -t My\ Doc\ Title]</tt>.  #document will automatically
+  # call RDoc::Options#finish if an options instance was given.
+  #
+  # For a list of options, see either RDoc::Options or <tt>rdoc --help</tt>.
   #
-  # 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 <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.
+  # By default, output will be stored in a directory called "doc" below the
+  # current directory, so make sure you're somewhere writable before invoking.
 
-  def document(argv)
-    RDoc::TopLevel.reset
-    RDoc::Parser::C.reset
+  def document options
+    self.store = RDoc::Store.new
 
-    @options = RDoc::Options.new
-    @options.parse argv
+    if RDoc::Options === options then
+      @options = options
+      @options.finish
+    else
+      @options = load_options
+      @options.parse options
+    end
 
     if @options.pipe then
       handle_pipe
       exit
     end
 
-    @exclude = @options.exclude
-
     unless @options.coverage_report then
       @last_modified = setup_output_dir @options.op_dir, @options.force_update
     end
 
-    start_time = Time.now
+    @store.encoding = @options.encoding
+    @store.dry_run  = @options.dry_run
+    @store.main     = @options.main_page
+    @store.title    = @options.title
+    @store.path     = @options.op_dir
+
+    @start_time = Time.now
+
+    @store.load_cache
 
     file_info = parse_files @options.files
 
     @options.default_title = "RDoc Documentation"
 
-    RDoc::TopLevel.complete @options.visibility
+    @store.complete @options.visibility
+
+    @stats.coverage_level = @options.coverage_report
 
     if @options.coverage_report then
       puts
-      puts @stats.report
-    elsif file_info.empty?
+
+      puts @stats.report.accept RDoc::Markup::ToRdoc.new
+    elsif file_info.empty? then
       $stderr.puts "\nNo newer files." unless @options.quiet
     else
       gen_klass = @options.generator
 
-      @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 = gen_klass.new @store, @options
 
-          @generator.generate file_info
-          update_output_dir ".", start_time, @last_modified
-        ensure
-          self.class.current = nil
-        end
-      end
+      generate
     end
 
-    unless @options.quiet or not @stats then
+    if @stats and (@options.coverage_report or not @options.quiet) then
       puts
-      puts @stats.summary
+      puts @stats.summary.accept RDoc::Markup::ToRdoc.new
     end
 
     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
+    if @options.dry_run then
+      # do nothing
+      @generator.generate
+    else
+      Dir.chdir @options.op_dir do
+        unless @options.quiet then
+          $stderr.puts "\nGenerating #{@generator.class.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
+        end
+
+        @generator.generate
+        update_output_dir '.', @start_time, @last_modified
+      end
+    end
+  end
+
   ##
   # Removes a siginfo handler and replaces the previous
 
@@ -466,21 +560,20 @@ end
 begin
   require 'rubygems'
 
-  if Gem.respond_to? :find_files then
-    rdoc_extensions = Gem.find_files 'rdoc/discover'
+  rdoc_extensions = Gem.find_files 'rdoc/discover'
 
-    rdoc_extensions.each do |extension|
-      begin
-        load extension
-      rescue => e
-        warn "error loading #{extension.inspect}: #{e.message} (#{e.class})"
-      end
+  rdoc_extensions.each do |extension|
+    begin
+      load extension
+    rescue => e
+      warn "error loading #{extension.inspect}: #{e.message} (#{e.class})"
+      warn "\t#{e.backtrace.join "\n\t"}" if $DEBUG
     end
   end
 rescue LoadError
 end
 
 # require built-in generators after discovery in case they've been replaced
-require 'rdoc/generator/darkfish'
-require 'rdoc/generator/ri'
-
+require_relative 'generator/darkfish'
+require_relative 'generator/ri'
+require_relative 'generator/pot'

data/lib/rdoc/require.rb

@@ -1,5 +1,4 @@
-require 'rdoc/code_object'
-
+# frozen_string_literal: true
 ##
 # A file loaded by \#require