rdoc 6.3.4.1 → 8.0.0

data/lib/rdoc/rdoc.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
-require 'rdoc'
+require_relative '../rdoc'
 
 require 'find'
 require 'fileutils'
 require 'pathname'
 require 'time'
+require_relative 'rbs_helper'
 
 ##
 # This is the driver for generating RDoc output.  It handles file parsing and
@@ -14,7 +15,7 @@ require 'time'
 # is:
 #
 #   rdoc = RDoc::RDoc.new
-#   options = rdoc.load_options # returns an RDoc::Options instance
+#   options = RDoc::Options.load_options # returns an RDoc::Options instance
 #   # set extra options
 #   rdoc.document options
 #
@@ -35,6 +36,17 @@ class RDoc::RDoc
 
   GENERATORS = {}
 
+  ##
+  # List of directory names always skipped
+
+  UNCONDITIONALLY_SKIPPED_DIRECTORIES = %w[CVS .svn .git].freeze
+
+  ##
+  # List of directory names skipped if test suites should be skipped
+
+  TEST_SUITE_DIRECTORY_NAMES = %w[spec test].freeze
+
+
   ##
   # Generator instance used for creating output
 
@@ -58,7 +70,7 @@ class RDoc::RDoc
   ##
   # The current documentation store
 
-  attr_reader :store
+  attr_accessor :store
 
   ##
   # Add +klass+ that can generate output after parsing
@@ -78,7 +90,7 @@ class RDoc::RDoc
   ##
   # Sets the active RDoc::RDoc instance
 
-  def self.current= rdoc
+  def self.current=(rdoc)
     @current = rdoc
   end
 
@@ -107,8 +119,8 @@ class RDoc::RDoc
   # Gathers a set of parseable files from the files and directories listed in
   # +files+.
 
-  def gather_files files
-    files = ["."] if files.empty?
+  def gather_files(files)
+    files = [@options.root.to_s] if files.empty?
 
     file_list = normalized_file_list files, true, @options.exclude
 
@@ -129,7 +141,7 @@ class RDoc::RDoc
   # Turns RDoc from stdin into HTML
 
   def handle_pipe
-    @html = RDoc::Markup::ToHtml.new @options
+    @html = RDoc::Markup::ToHtml.new(pipe: @options.pipe, output_decoration: @options.output_decoration)
 
     parser = RDoc::Text::MARKUP_FORMAT[@options.markup]
 
@@ -151,35 +163,6 @@ 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.safe_load_file '.rdoc_options', permitted_classes: [RDoc::Options, Symbol]
-    rescue Psych::SyntaxError
-      raise RDoc::Error, "#{options_file} is not a valid rdoc options file"
-    end
-
-    return RDoc::Options.new unless options # 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
@@ -226,15 +209,6 @@ option)
     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.
 
@@ -264,7 +238,7 @@ option)
   # representing candidates for documentation. It may also contain comments
   # (starting with '#')
 
-  def parse_dot_doc_file in_dir, filename
+  def parse_dot_doc_file(in_dir, filename)
     # read and strip comments
     patterns = File.read(filename).gsub(/#.*/, '')
 
@@ -309,7 +283,10 @@ option)
           file_list[rel_file_name] = mtime
         end
       when "directory" then
-        next if rel_file_name == "CVS" || rel_file_name == ".svn"
+        next if UNCONDITIONALLY_SKIPPED_DIRECTORIES.include?(rel_file_name)
+
+        basename = File.basename(rel_file_name)
+        next if options.skip_tests && TEST_SUITE_DIRECTORY_NAMES.include?(basename)
 
         created_rid = File.join rel_file_name, "created.rid"
         next if File.file? created_rid
@@ -335,7 +312,7 @@ option)
   # files. However we may well contain subdirectories which must be tested
   # for .document files.
 
-  def list_files_in_directory dir
+  def list_files_in_directory(dir)
     files = Dir.glob File.join(dir, "*")
 
     normalized_file_list files, false, @options.exclude
@@ -344,7 +321,7 @@ option)
   ##
   # Parses +filename+ and returns an RDoc::TopLevel
 
-  def parse_file filename
+  def parse_file(filename)
     encoding = @options.encoding
     filename = filename.encode encoding
 
@@ -356,22 +333,9 @@ option)
 
     return unless content
 
-    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
+    top_level = @store.add_file filename, relative_name: relative_path_for(filename)
 
-    parser = RDoc::Parser.for top_level, filename, content, @options, @stats
+    parser = RDoc::Parser.for top_level, content, @options, @stats
 
     return unless parser
 
@@ -393,13 +357,25 @@ 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
+    syntax_check_command = syntax_check_command_for filename, parser&.class
+    syntax_check_message = if syntax_check_command
+      <<~MESSAGE
 Before reporting this, could you check that the file you're documenting
 has proper syntax:
 
-  #{Gem.ruby} -c #{filename}
+  #{syntax_check_command}
+      MESSAGE
+    else
+      <<~MESSAGE
+Before reporting this, could you check that the file you're documenting
+has proper syntax for its language?
+      MESSAGE
+    end
 
-RDoc is not a full Ruby parser and will fail when fed invalid ruby programs.
+    $stderr.puts <<-EOF
+#{syntax_check_message}
+RDoc's parsers are not full language parsers and may fail when fed invalid
+source files.
 
 The internal error was:
 
@@ -410,18 +386,50 @@ The internal error was:
     $stderr.puts e.backtrace.join("\n\t") if $DEBUG_RDOC
 
     raise e
-    nil
+  end
+
+  def syntax_check_command_for(filename, parser_class = RDoc::Parser.can_parse_by_name(filename))
+    if parser_class == RDoc::Parser::Ruby
+      "#{Gem.ruby} -c #{filename}"
+    elsif parser_class == RDoc::Parser::C
+      cc = ENV['CC']
+      cc = 'cc' if cc.nil? || cc.empty?
+      "#{cc} -fsyntax-only #{filename}"
+    end
+  end
+
+  ##
+  # Returns the relative path for +filename+ against +options.root+ (and
+  # +options.page_dir+ when set).  This is the key used by RDoc::Store to
+  # identify files.
+
+  def relative_path_for(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 &&
+       relative_path.to_s.start_with?(@options.page_dir.to_s)
+      relative_path =
+        relative_path.relative_path_from @options.page_dir
+    end
+
+    relative_path.to_s
   end
 
   ##
   # Parse each file on the command line, recursively entering directories.
 
-  def parse_files files
+  def parse_files(files)
     file_list = gather_files files
     @stats = RDoc::Stats.new @store, file_list.length, @options.verbosity
 
     return [] if file_list.empty?
 
+    # This workaround can be removed after the :main: directive is removed
     original_options = @options.dup
     @stats.begin_adding
 
@@ -430,6 +438,8 @@ The internal error was:
       parse_file filename
     end.compact
 
+    @store.resolve_c_superclasses
+
     @stats.done_adding
     @options = original_options
 
@@ -440,13 +450,11 @@ The internal error was:
   # Removes file extensions known to be unparseable from +files+ and TAGS
   # files for emacs and vim.
 
-  def remove_unparseable files
+  def remove_unparseable(files)
     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_)/
-         })
+      file =~ /\.(?:class|eps|erb|scpt\.txt|svg|ttf|yml)\z/i or
+        (file =~ /tags\z/i and
+         /\A(\f\n[^,]+,\d+$|!_TAG_)/.match?(File.binread(file, 100)))
     end
   end
 
@@ -464,40 +472,60 @@ The internal error was:
   # 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 options
-    self.store = RDoc::Store.new
-
+  def document(options)
     if RDoc::Options === options then
       @options = options
-      @options.finish
     else
-      @options = load_options
+      @options = RDoc::Options.load_options
       @options.parse options
     end
+    @options.finish
+
+    @store = RDoc::Store.new(@options)
 
     if @options.pipe then
       handle_pipe
       exit
     end
 
+    if @options.server_port
+      @store.load_cache
+
+      parse_files @options.files
+      record_auto_discovered_rbs_signature_mtimes
+
+      @options.default_title = "RDoc Documentation"
+
+      load_auto_discovered_rbs_signatures
+      @store.complete @options.visibility
+
+      start_server
+      exit
+    end
+
     unless @options.coverage_report then
       @last_modified = setup_output_dir @options.op_dir, @options.force_update
     end
 
-    @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
 
+    auto_discovered_rbs_signatures_changed = auto_discovered_rbs_signatures_changed?
+    # When only auto-discovered RBS signatures changed, no Ruby file would be
+    # reparsed under normal mtime checks.  The store cache holds class metadata
+    # but not live RDoc::Context objects, so the generator would have nothing
+    # to iterate.  Force a full reparse so updated signatures show up in the
+    # rendered output.
+    @last_modified.clear if auto_discovered_rbs_signatures_changed
+
     file_info = parse_files @options.files
+    record_auto_discovered_rbs_signature_mtimes
 
     @options.default_title = "RDoc Documentation"
 
+    load_auto_discovered_rbs_signatures
+
     @store.complete @options.visibility
 
     @stats.coverage_level = @options.coverage_report
@@ -505,8 +533,8 @@ The internal error was:
     if @options.coverage_report then
       puts
 
-      puts @stats.report.accept RDoc::Markup::ToRdoc.new
-    elsif file_info.empty? then
+      puts @stats.report
+    elsif file_info.empty? && !auto_discovered_rbs_signatures_changed then
       $stderr.puts "\nNo newer files." unless @options.quiet
     else
       gen_klass = @options.generator
@@ -518,7 +546,7 @@ The internal error was:
 
     if @stats and (@options.coverage_report or not @options.quiet) then
       puts
-      puts @stats.summary.accept RDoc::Markup::ToRdoc.new
+      puts @stats.summary
     end
 
     exit @stats.fully_documented? if @options.coverage_report
@@ -537,6 +565,9 @@ The internal error was:
       Dir.chdir @options.op_dir do
         unless @options.quiet then
           $stderr.puts "\nGenerating #{@generator.class.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
+          uri = "file://#{Dir.pwd}/index.html"
+          ref = $stderr.tty? ? "\e]8;;#{uri}\e\\#{uri}\e]8;;\e\\" : uri
+          $stderr.puts "\nYou can visit the home page at: #{ref}"
         end
 
         @generator.generate
@@ -545,6 +576,99 @@ The internal error was:
     end
   end
 
+  ##
+  # Loads RBS type signatures from the project's +sig+ directory and RBS
+  # stdlib, then merges them into the store's code objects.
+
+  def load_auto_discovered_rbs_signatures
+    sig_dirs = []
+    sig_dir = File.join(@options.root.to_s, 'sig')
+    sig_dirs << sig_dir if File.directory?(sig_dir)
+    signatures = RDoc::RbsHelper.load_signatures(*sig_dirs)
+    @store.merge_rbs_signatures(signatures)
+  rescue RBS::BaseError, Errno::ENOENT, LoadError => e
+    # In server mode, a previous successful load may have populated the store;
+    # drop those signatures so a now-broken sig file doesn't keep showing
+    # stale types alongside the warning.
+    @store.clear_rbs_signatures
+    @options.warn "Failed to load RBS type signatures: #{e.message}"
+  end
+
+  ##
+  # Returns RBS files that RDoc auto-discovers for signature loading.
+
+  def auto_discovered_rbs_signature_files
+    Dir[File.join(@options.root.to_s, 'sig', '**', '*.rbs')].sort
+  end
+
+  ##
+  # Returns true if any auto-discovered RBS signature file has changed since
+  # the last run.
+
+  def auto_discovered_rbs_signatures_changed?
+    current = auto_discovered_rbs_signature_mtimes
+    previous = @last_modified.select { |file, _| auto_discovered_rbs_signature_file?(file) }
+
+    return true unless (previous.keys - current.keys).empty?
+
+    current.any? do |file, mtime|
+      last_modified = @last_modified[file]
+      last_modified.nil? || mtime.to_i > last_modified.to_i
+    end
+  end
+
+  ##
+  # Records auto-discovered RBS signature file mtimes so normal generation
+  # freshness checks and the live server watcher can see signature-only edits.
+
+  def record_auto_discovered_rbs_signature_mtimes
+    @last_modified.reject! { |file, _| auto_discovered_rbs_signature_file?(file) }
+    @last_modified.merge! auto_discovered_rbs_signature_mtimes
+  end
+
+  ##
+  # Files watched by the live preview server.
+
+  def watch_files
+    (@last_modified.keys + auto_discovered_rbs_signature_files).uniq
+  end
+
+  ##
+  # Returns true for project RBS files that are auto-discovered for signature
+  # loading. RDoc parses any selected .rbs file as documentation input, but
+  # only +sig/**/*.rbs+ files are loaded through RBS::EnvironmentLoader for
+  # type signature merging and live-reload bookkeeping.
+
+  def auto_discovered_rbs_signature_file?(file) # :nodoc:
+    return false unless File.extname(file) == '.rbs'
+
+    root = Pathname(@options.root.to_s).expand_path
+    relative_path = Pathname(file).expand_path.relative_path_from root
+    relative_path.each_filename.first == 'sig'
+  rescue ArgumentError
+    # file and root may be on different drives on Windows
+    false
+  end
+
+  ##
+  # Returns mtimes for auto-discovered RBS signature files.
+
+  def auto_discovered_rbs_signature_mtimes # :nodoc:
+    auto_discovered_rbs_signature_files.each_with_object({}) do |file, mtimes|
+      mtime = RDoc.safe_mtime(file)
+      mtimes[file] = mtime if mtime
+    end
+  end
+
+  ##
+  # Starts a live-reloading HTTP server for previewing documentation.
+  # Called from #document when <tt>--server</tt> is given.
+
+  def start_server
+    server = RDoc::Server.new(self, @options.server_port)
+    server.start
+  end
+
   ##
   # Removes a siginfo handler and replaces the previous
 
@@ -556,14 +680,33 @@ The internal error was:
     trap 'INFO', handler
   end
 
+  ##
+  # Returns true when +extension+ is the RBS gem's RDoc discovery hook.
+  # Released RBS gems install their plugin through this hook, so skip it to
+  # avoid replacing the built-in parser during discovery.
+
+  def self.rbs_discovery_extension?(extension) # :nodoc:
+    extension = File.expand_path(extension)
+
+    Gem::Specification.find_all_by_name('rbs').any? do |spec|
+      File.expand_path('lib/rdoc/discover.rb', spec.full_gem_path) == extension
+    end
+  end
+
 end
 
+# Load built-in parser registrations before RubyGems discovery, then skip the
+# RBS gem's plugin hook so it cannot replace RDoc::Parser::RBS.
+require_relative 'parser'
+
 begin
   require 'rubygems'
 
-  rdoc_extensions = Gem.find_files 'rdoc/discover'
+  rdoc_extensions = Gem.find_latest_files 'rdoc/discover'
 
   rdoc_extensions.each do |extension|
+    next if RDoc::RDoc.rbs_discovery_extension?(extension)
+
     begin
       load extension
     rescue => e
@@ -576,5 +719,6 @@ end
 
 # require built-in generators after discovery in case they've been replaced
 require_relative 'generator/darkfish'
+require_relative 'generator/aliki'
 require_relative 'generator/ri'
 require_relative 'generator/pot'