rdoc 7.2.0 → 8.0.0

data/lib/rdoc/rdoc.rb

@@ -5,6 +5,7 @@ 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
@@ -140,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]
 
@@ -332,20 +333,7 @@ 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, content, @options, @stats
 
@@ -369,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:
 
@@ -388,6 +388,38 @@ The internal error was:
     raise e
   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.
 
@@ -420,8 +452,8 @@ The internal error was:
 
   def remove_unparseable(files)
     files.reject do |file, *|
-      file =~ /\.(?:class|eps|erb|scpt\.txt|svg|ttf|yml)$/i or
-        (file =~ /tags$/i and
+      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
@@ -456,6 +488,21 @@ The internal error was:
       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
@@ -464,10 +511,21 @@ The internal error was:
 
     @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
@@ -475,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
@@ -488,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
@@ -507,7 +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}..."
-          $stderr.puts "\nYou can visit the home page at: \e]8;;file://#{Dir.pwd}/index.html\e\\file://#{Dir.pwd}/index.html\e]8;;\e\\"
+          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
@@ -516,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
 
@@ -527,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_latest_files 'rdoc/discover'
 
   rdoc_extensions.each do |extension|
+    next if RDoc::RDoc.rbs_discovery_extension?(extension)
+
     begin
       load extension
     rescue => e

data/lib/rdoc/ri/driver.rb

@@ -1218,7 +1218,7 @@ or the PAGER environment variable.
     comment = RDoc::Comment.new("missing documentation at #{e.file}")
     comment.parse
 
-    method = RDoc::AnyMethod.new nil, name
+    method = RDoc::AnyMethod.new name
     method.comment = comment
     method
   end
@@ -1415,6 +1415,8 @@ or the PAGER environment variable.
     out << RDoc::Markup::Rule.new(1)
 
     render_method_arguments out, method.arglists
+    sig = method.type_signature_lines || store.rbs_signature_for(method)
+    render_method_type_signature out, sig if sig
     render_method_superclass out, method
     if method.is_alias_for
       al = method.is_alias_for
@@ -1452,6 +1454,10 @@ or the PAGER environment variable.
     end
   end
 
+  def render_method_type_signature(out, lines) # :nodoc:
+    out << RDoc::Markup::Verbatim.new(*lines.map { |s| s + "\n" })
+  end
+
   def render_method_superclass(out, method) # :nodoc:
     return unless
       method.respond_to?(:superclass_method) and method.superclass_method
@@ -1521,7 +1527,7 @@ or the PAGER environment variable.
 
     extra_doc_dirs = @stores.map {|s| s.type == :extra ? s.path : nil}.compact
 
-    server.mount '/', RDoc::Servlet, nil, extra_doc_dirs
+    server.mount '/', RDoc::RI::Servlet, nil, extra_doc_dirs
 
     trap 'INT'  do server.shutdown end
     trap 'TERM' do server.shutdown end

data/lib/rdoc/ri/paths.rb

@@ -30,7 +30,7 @@ module RDoc::RI::Paths
   # :extra:: ri data directory from the command line.  Yielded for each
   #          entry in +extra_dirs+
 
-  def self.each system = true, site = true, home = true, gems = :latest, *extra_dirs # :yields: directory, type
+  def self.each(system = true, site = true, home = true, gems = :latest, *extra_dirs) # :yields: directory, type
     return enum_for __method__, system, site, home, gems, *extra_dirs unless
       block_given?
 

data/lib/rdoc/{servlet.rb → ri/servlet.rb}

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-require_relative '../rdoc'
+require_relative '../../rdoc'
 require 'erb'
 require 'time'
 require 'json'
@@ -24,14 +24,14 @@ end
 #
 #   server = WEBrick::HTTPServer.new Port: 8000
 #
-#   server.mount '/', RDoc::Servlet
+#   server.mount '/', RDoc::RI::Servlet
 #
 # If you want to mount the servlet some other place than the root, provide the
 # base path when mounting:
 #
-#   server.mount '/rdoc', RDoc::Servlet, '/rdoc'
+#   server.mount '/rdoc', RDoc::RI::Servlet, '/rdoc'
 
-class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
+class RDoc::RI::Servlet < WEBrick::HTTPServlet::AbstractServlet
 
   @server_stores = Hash.new { |hash, server| hash[server] = {} }
   @cache         = Hash.new { |hash, store|  hash[store]  = {} }
@@ -50,7 +50,7 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
   # Creates an instance of this servlet that shares cached data between
   # requests.
 
-  def self.get_instance server, *options # :nodoc:
+  def self.get_instance(server, *options) # :nodoc:
     stores = @server_stores[server]
 
     new server, stores, @cache, *options

data/lib/rdoc/ri.rb

@@ -13,8 +13,9 @@ module RDoc::RI
 
   class Error < RDoc::Error; end
 
-  autoload :Driver, "#{__dir__}/ri/driver"
-  autoload :Paths,  "#{__dir__}/ri/paths"
-  autoload :Store,  "#{__dir__}/ri/store"
+  autoload :Driver,  "#{__dir__}/ri/driver"
+  autoload :Paths,   "#{__dir__}/ri/paths"
+  autoload :Servlet, "#{__dir__}/ri/servlet"
+  autoload :Store,   "#{__dir__}/ri/store"
 
 end

data/lib/rdoc/rubygems_hook.rb

@@ -254,18 +254,18 @@ class RDoc::RubyGemsHook
 
 end
 
-# This class is referenced by RubyGems to create documents.
-# All implementations are moved to the above RubyGemsHook.
-#
-# This class does nothing when this RDoc is installed as a normal gem
-# or a bundled gem.
-#
-# This class does generate/remove documents for compatibility when
-# this RDoc is installed as a default gem.
-#
-# We can remove this when all maintained RubyGems remove
-# `rubygems/rdoc.rb`.
 module RDoc
+  # This class is referenced by RubyGems to create documents.
+  # All implementations are moved to the above RubyGemsHook.
+  #
+  # This class does nothing when this RDoc is installed as a normal gem
+  # or a bundled gem.
+  #
+  # This class does generate/remove documents for compatibility when
+  # this RDoc is installed as a default gem.
+  #
+  # We can remove this when all maintained RubyGems remove
+  # `rubygems/rdoc.rb`.
   class RubygemsHook
 
     attr_accessor :generate_rdoc, :generate_ri, :force