rdoc 5.1.0 → 6.13.1

data/lib/rdoc/store.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 require 'fileutils'
 
 ##
@@ -94,11 +94,7 @@ class RDoc::Store
 
   attr_accessor :path
 
-  ##
-  # The RDoc::RDoc driver for this parse tree.  This allows classes consulting
-  # the documentation tree to access user-set options, for example.
-
-  attr_accessor :rdoc
+  attr_reader :options
 
   ##
   # Type of ri datastore this was loaded from.  See RDoc::RI::Driver,
@@ -116,14 +112,19 @@ class RDoc::Store
 
   attr_accessor :encoding
 
+  ##
+  # The lazy constants alias will be discovered in passing
+
+  attr_reader :unmatched_constant_alias
+
   ##
   # Creates a new Store of +type+ that will load or save to +path+
 
-  def initialize path = nil, type = nil
-    @dry_run  = false
-    @encoding = nil
-    @path     = path
-    @rdoc     = nil
+  def initialize(options, path: nil, type: nil)
+    @options  = options
+    @dry_run  = options.dry_run
+    @encoding = options.encoding
+    @path     = path || options.op_dir
     @type     = type
 
     @cache = {
@@ -134,15 +135,16 @@ class RDoc::Store
       :c_singleton_class_variables => {},
       :encoding                    => @encoding,
       :instance_methods            => {},
-      :main                        => nil,
+      :main                        => options.main_page,
       :modules                     => [],
       :pages                       => [],
-      :title                       => nil,
+      :title                       => options.title,
     }
 
     @classes_hash = {}
     @modules_hash = {}
     @files_hash   = {}
+    @text_files_hash = {}
 
     @c_enclosure_classes = {}
     @c_enclosure_names   = {}
@@ -152,6 +154,8 @@ class RDoc::Store
 
     @unique_classes = nil
     @unique_modules = nil
+
+    @unmatched_constant_alias = {}
   end
 
   ##
@@ -177,16 +181,39 @@ class RDoc::Store
   # Adds the file with +name+ as an RDoc::TopLevel to the store.  Returns the
   # created RDoc::TopLevel.
 
-  def add_file absolute_name, relative_name = absolute_name
+  def add_file absolute_name, relative_name: absolute_name, parser: nil
     unless top_level = @files_hash[relative_name] then
       top_level = RDoc::TopLevel.new absolute_name, relative_name
+      top_level.parser = parser if parser
       top_level.store = self
       @files_hash[relative_name] = top_level
+      @text_files_hash[relative_name] = top_level if top_level.text?
     end
 
     top_level
   end
 
+  ##
+  # Make sure any references to C variable names are resolved to the corresponding class.
+  #
+
+  def resolve_c_superclasses
+    @classes_hash.each_value do |klass|
+      if klass.superclass.is_a?(String) && (candidate = find_c_enclosure(klass.superclass))
+        klass.superclass = candidate
+      end
+    end
+  end
+
+  ##
+  # Sets the parser of +absolute_name+, unless it from a source code file.
+
+  def update_parser_of_file(absolute_name, parser)
+    if top_level = @files_hash[absolute_name] then
+      @text_files_hash[absolute_name] = top_level if top_level.text?
+    end
+  end
+
   ##
   # Returns all classes discovered by RDoc
 
@@ -421,8 +448,8 @@ class RDoc::Store
   # +file_name+
 
   def find_text_page file_name
-    @files_hash.each_value.find do |file|
-      file.text? and file.full_name == file_name
+    @text_files_hash.each_value.find do |file|
+      file.full_name == file_name
     end
   end
 
@@ -466,7 +493,7 @@ class RDoc::Store
     when :gem    then
       parent = File.expand_path '..', @path
       "gem #{File.basename parent}"
-    when :home   then '~/.rdoc'
+    when :home   then RDoc.home
     when :site   then 'ruby site'
     when :system then 'ruby core'
     else @path
@@ -530,6 +557,7 @@ class RDoc::Store
     @cache[:pages].each do |page_name|
       page = load_page page_name
       @files_hash[page_name] = page
+      @text_files_hash[page_name] = page if page.text?
     end
   end
 
@@ -539,9 +567,7 @@ class RDoc::Store
   def load_cache
     #orig_enc = @encoding
 
-    open cache_path, 'rb' do |io|
-      @cache = Marshal.load io.read
-    end
+    @cache = marshal_load(cache_path)
 
     load_enc = @cache[:encoding]
 
@@ -585,6 +611,8 @@ class RDoc::Store
     case obj
     when RDoc::NormalClass then
       @classes_hash[klass_name] = obj
+    when RDoc::SingleClass then
+      @classes_hash[klass_name] = obj
     when RDoc::NormalModule then
       @modules_hash[klass_name] = obj
     end
@@ -596,9 +624,7 @@ class RDoc::Store
   def load_class_data klass_name
     file = class_file klass_name
 
-    open file, 'rb' do |io|
-      Marshal.load io.read
-    end
+    marshal_load(file)
   rescue Errno::ENOENT => e
     error = MissingFileError.new(self, file, klass_name)
     error.set_backtrace e.backtrace
@@ -611,14 +637,10 @@ class RDoc::Store
   def load_method klass_name, method_name
     file = method_file klass_name, method_name
 
-    open file, 'rb' do |io|
-      obj = Marshal.load io.read
-      obj.store = self
-      obj.parent =
-        find_class_or_module(klass_name) || load_class(klass_name) unless
-          obj.parent
-      obj
-    end
+    obj = marshal_load(file)
+    obj.store = self
+    obj.parent ||= find_class_or_module(klass_name) || load_class(klass_name)
+    obj
   rescue Errno::ENOENT => e
     error = MissingFileError.new(self, file, klass_name + method_name)
     error.set_backtrace e.backtrace
@@ -631,11 +653,9 @@ class RDoc::Store
   def load_page page_name
     file = page_file page_name
 
-    open file, 'rb' do |io|
-      obj = Marshal.load io.read
-      obj.store = self
-      obj
-    end
+    obj = marshal_load(file)
+    obj.store = self
+    obj
   rescue Errno::ENOENT => e
     error = MissingFileError.new(self, file, page_name)
     error.set_backtrace e.backtrace
@@ -703,8 +723,8 @@ class RDoc::Store
   # Returns the RDoc::TopLevel that is a text file and has the given +name+
 
   def page name
-    @files_hash.each_value.find do |file|
-      file.text? and file.page_name == name
+    @text_files_hash.each_value.find do |file|
+      file.page_name == name or file.base_name == name
     end
   end
 
@@ -742,7 +762,7 @@ class RDoc::Store
         save_method klass, method
       end
 
-      klass.each_attribute do |attribute|
+      klass.attributes.each do |attribute|
         save_method klass, attribute
       end
     end
@@ -776,10 +796,8 @@ class RDoc::Store
 
     return if @dry_run
 
-    marshal = Marshal.dump @cache
-
-    open cache_path, 'wb' do |io|
-      io.write marshal
+    File.open cache_path, 'wb' do |io|
+      Marshal.dump @cache, io
     end
   end
 
@@ -852,10 +870,8 @@ class RDoc::Store
 
     FileUtils.rm_f to_delete
 
-    marshal = Marshal.dump klass
-
-    open path, 'wb' do |io|
-      io.write marshal
+    File.open path, 'wb' do |io|
+      Marshal.dump klass, io
     end
   end
 
@@ -877,10 +893,8 @@ class RDoc::Store
 
     return if @dry_run
 
-    marshal = Marshal.dump method
-
-    open method_file(full_name, method.full_name), 'wb' do |io|
-      io.write marshal
+    File.open method_file(full_name, method.full_name), 'wb' do |io|
+      Marshal.dump method, io
     end
   end
 
@@ -899,10 +913,8 @@ class RDoc::Store
 
     return if @dry_run
 
-    marshal = Marshal.dump page
-
-    open path, 'wb' do |io|
-      io.write marshal
+    File.open path, 'wb' do |io|
+      Marshal.dump page, io
     end
   end
 
@@ -965,4 +977,21 @@ class RDoc::Store
     @unique_modules
   end
 
+  private
+  def marshal_load(file)
+    File.open(file, 'rb') {|io| Marshal.load(io, MarshalFilter)}
+  end
+
+  MarshalFilter = proc do |obj|
+    case obj
+    when true, false, nil, Array, Class, Encoding, Hash, Integer, String, Symbol, RDoc::Text
+    else
+      unless obj.class.name.start_with?("RDoc::")
+        raise TypeError, "not permitted class: #{obj.class.name}"
+      end
+    end
+    obj
+  end
+  private_constant :MarshalFilter
+
 end

data/lib/rdoc/task.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 #--
 # Copyright (c) 2003, 2004 Jim Weirich, 2009 Eric Hodel
 #
@@ -32,7 +32,7 @@ begin
 rescue Gem::LoadError
 end unless defined?(Rake)
 
-require 'rdoc'
+require_relative '../rdoc'
 require 'rake'
 require 'rake/tasklib'
 
@@ -50,6 +50,9 @@ require 'rake/tasklib'
 # [rerdoc]
 #   Rebuild the rdoc files from scratch, even if they are not out of date.
 #
+# [rdoc:coverage]
+#   Print RDoc coverage report for all rdoc files.
+#
 # Simple Example:
 #
 #   require 'rdoc/task'
@@ -71,7 +74,7 @@ require 'rake/tasklib'
 #   require 'rdoc/task'
 #
 #   RDoc::Task.new :rdoc_dev do |rdoc|
-#     rdoc.main = "README.doc"
+#     rdoc.main = "README.rdoc"
 #     rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
 #     rdoc.options << "--all"
 #   end
@@ -90,8 +93,8 @@ require 'rake/tasklib'
 #   RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
 #                  :rerdoc => "rdoc:force")
 #
-# This will create the tasks <tt>:rdoc</tt>, <tt>:rdoc:clean</tt> and
-# <tt>:rdoc:force</tt>.
+# This will create the tasks <tt>:rdoc</tt>, <tt>:rdoc:clean</tt>,
+# <tt>:rdoc:force</tt>, and <tt>:rdoc:coverage</tt>.
 
 class RDoc::Task < Rake::TaskLib
 
@@ -101,9 +104,8 @@ class RDoc::Task < Rake::TaskLib
   attr_accessor :name
 
   ##
-  # Comment markup format.  rdoc, rd and tomdoc are supported.  (default is
-  # 'rdoc')
-
+  # The markup format; one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+  # See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
   attr_accessor :markup
 
   ##
@@ -128,7 +130,7 @@ class RDoc::Task < Rake::TaskLib
   attr_accessor :template
 
   ##
-  # Name of format generator (<tt>--format<tt>) used by rdoc. (defaults to
+  # Name of format generator (<tt>--format</tt>) used by rdoc. (defaults to
   # rdoc's default)
 
   attr_accessor :generator
@@ -248,6 +250,18 @@ class RDoc::Task < Rake::TaskLib
       RDoc::RDoc.new.document args
     end
 
+    namespace rdoc_task_name do
+      desc coverage_task_description
+      task coverage_task_name do
+        @before_running_rdoc.call if @before_running_rdoc
+        opts = option_list << "-C"
+        args = opts + @rdoc_files
+
+        $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
+        RDoc::RDoc.new.document args
+      end
+    end
+
     self
   end
 
@@ -288,6 +302,13 @@ class RDoc::Task < Rake::TaskLib
     "Rebuild RDoc HTML files"
   end
 
+  ##
+  # Task description for the coverage task or its renamed description
+
+  def coverage_task_description
+    "Print RDoc coverage report"
+  end
+
   private
 
   def rdoc_target
@@ -315,6 +336,10 @@ class RDoc::Task < Rake::TaskLib
     end
   end
 
+  def coverage_task_name
+    "coverage"
+  end
+
 end
 
 # :stopdoc:
@@ -323,7 +348,7 @@ module Rake
   ##
   # For backwards compatibility
 
-  RDocTask = RDoc::Task
+  RDocTask = RDoc::Task # :nodoc:
 
 end
 # :startdoc:

data/lib/rdoc/text.rb

@@ -1,26 +1,21 @@
-# coding: utf-8
-# frozen_string_literal: false
+# frozen_string_literal: true
 
 ##
 # For RDoc::Text#to_html
 
 require 'strscan'
 
-##
-# For RDoc::Text#snippet
-
-begin
-  gem 'json'
-rescue NameError => e # --disable-gems
-  raise unless e.name == :gem
-rescue Gem::LoadError
-end
-
 ##
 # Methods for manipulating comment text
 
 module RDoc::Text
 
+  ##
+  # The language for this text.  This affects stripping comments
+  # markers.
+
+  attr_accessor :language
+
   ##
   # Maps markup formats to classes that can parse them.  If the format is
   # unknown, "rdoc" format is used.
@@ -71,7 +66,7 @@ module RDoc::Text
     text.each_line do |line|
       nil while line.gsub!(/(?:\G|\r)((?:.{8})*?)([^\t\r\n]{0,7})\t/) do
         r = "#{$1}#{$2}#{' ' * (8 - $2.size)}"
-        r.force_encoding text.encoding
+        r = RDoc::Encoding.change_encoding r, text.encoding
         r
       end
 
@@ -93,7 +88,7 @@ module RDoc::Text
     end
 
     empty = ''
-    empty.force_encoding text.encoding
+    empty = RDoc::Encoding.change_encoding empty, text.encoding
 
     text.gsub(/^ {0,#{indent}}/, empty)
   end
@@ -104,8 +99,8 @@ module RDoc::Text
   # Requires the including class to implement #formatter
 
   def markup text
-    if @store.rdoc.options
-      locale = @store.rdoc.options.locale
+    if @store.options
+      locale = @store.options.locale
     else
       locale = nil
     end
@@ -122,8 +117,12 @@ module RDoc::Text
   def normalize_comment text
     return text if text.empty?
 
-    text = strip_stars    text
-    text = strip_hashes   text
+    case language
+    when :ruby
+      text = strip_hashes text
+    when :c
+      text = strip_stars text
+    end
     text = expand_tabs    text
     text = flush_left     text
     text = strip_newlines text
@@ -160,7 +159,7 @@ module RDoc::Text
     return text if text =~ /^(?>\s*)[^\#]/
 
     empty = ''
-    empty.force_encoding text.encoding
+    empty = RDoc::Encoding.change_encoding empty, text.encoding
 
     text.gsub(/^\s*(#+)/) { $1.tr '#', ' ' }.gsub(/^\s+$/, empty)
   end
@@ -180,17 +179,17 @@ module RDoc::Text
 
     encoding = text.encoding
 
-    text = text.gsub %r%Document-method:\s+[\w:.#=!?]+%, ''
+    text = text.gsub %r%Document-method:\s+[\w:.#=!?|^&<>~+\-/*\%@`\[\]]+%, ''
 
     space = ' '
-    space.force_encoding encoding if encoding
+    space = RDoc::Encoding.change_encoding space, encoding if encoding
 
     text.sub!  %r%/\*+%       do space * $&.length end
     text.sub!  %r%\*+/%       do space * $&.length end
     text.gsub! %r%^[ \t]*\*%m do space * $&.length end
 
     empty = ''
-    empty.force_encoding encoding if encoding
+    empty = RDoc::Encoding.change_encoding empty, encoding if encoding
     text.gsub(/^\s+$/, empty)
   end
 
@@ -199,7 +198,7 @@ module RDoc::Text
   # trademark symbols in +text+ to properly encoded characters.
 
   def to_html text
-    html = ''.encode text.encoding
+    html = (''.encode text.encoding).dup
 
     encoded = RDoc::Text::TO_HTML_CHARACTERS[text.encoding]
 
@@ -223,10 +222,10 @@ module RDoc::Text
       when s.scan(/\.\.\.(\.?)/) then
         html << s[1] << encoded[:ellipsis]
         after_word = nil
-      when s.scan(/\(c\)/) then
+      when s.scan(/\(c\)/i) then
         html << encoded[:copyright]
         after_word = nil
-      when s.scan(/\(r\)/) then
+      when s.scan(/\(r\)/i) then
         html << encoded[:trademark]
         after_word = nil
       when s.scan(/---/) then
@@ -242,10 +241,18 @@ module RDoc::Text
       when s.scan(/``/) then # backtick double quote
         html << encoded[:open_dquote]
         after_word = nil
-      when s.scan(/''/) then # tick double quote
+      when s.scan(/(?:&#39;|'){2}/) then # tick double quote
         html << encoded[:close_dquote]
         after_word = nil
-      when s.scan(/'/) then # single quote
+      when s.scan(/`/) then # backtick
+        if insquotes or after_word
+          html << '`'
+          after_word = false
+        else
+          html << encoded[:open_squote]
+          insquotes = true
+        end
+      when s.scan(/&#39;|'/) then # single quote
         if insquotes
           html << encoded[:close_squote]
           insquotes = false
@@ -306,4 +313,10 @@ module RDoc::Text
     res.join.strip
   end
 
+  ##
+  # Character class to be separated by a space when concatenating
+  # lines.
+
+  SPACE_SEPARATED_LETTER_CLASS = /[\p{Nd}\p{Lc}\p{Pc}]|[!-~&&\W]/
+
 end

data/lib/rdoc/token_stream.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # A TokenStream is a list of tokens, gathered during the parse of some entity
 # (say a method). Entities populate these streams by being registered with the
@@ -10,43 +10,61 @@ module RDoc::TokenStream
 
   ##
   # Converts +token_stream+ to HTML wrapping various tokens with
-  # <tt><span></tt> elements.  The following tokens types are wrapped in spans
-  # with the given class names:
-  #
-  # TkCONSTANT :: 'ruby-constant'
-  # TkKW       :: 'ruby-keyword'
-  # TkIVAR     :: 'ruby-ivar'
-  # TkOp       :: 'ruby-operator'
-  # TkId       :: 'ruby-identifier'
-  # TkNode     :: 'ruby-node'
-  # TkCOMMENT  :: 'ruby-comment'
-  # TkREGEXP   :: 'ruby-regexp'
-  # TkSTRING   :: 'ruby-string'
-  # TkVal      :: 'ruby-value'
-  #
-  # Other token types are not wrapped in spans.
+  # <tt><span></tt> elements. Some tokens types are wrapped in spans
+  # with the given class names. Other token types are not wrapped in spans.
 
   def self.to_html token_stream
+    starting_title = false
+
     token_stream.map do |t|
       next unless t
 
-      style = case t
-              when RDoc::RubyToken::TkCONSTANT then 'ruby-constant'
-              when RDoc::RubyToken::TkKW       then 'ruby-keyword'
-              when RDoc::RubyToken::TkIVAR     then 'ruby-ivar'
-              when RDoc::RubyToken::TkOp       then 'ruby-operator'
-              when RDoc::RubyToken::TkId       then 'ruby-identifier'
-              when RDoc::RubyToken::TkNode     then 'ruby-node'
-              when RDoc::RubyToken::TkCOMMENT  then 'ruby-comment'
-              when RDoc::RubyToken::TkREGEXP   then 'ruby-regexp'
-              when RDoc::RubyToken::TkSTRING   then 'ruby-string'
-              when RDoc::RubyToken::TkVal      then 'ruby-value'
+      style = case t[:kind]
+              when :on_const   then 'ruby-constant'
+              when :on_kw      then 'ruby-keyword'
+              when :on_ivar    then 'ruby-ivar'
+              when :on_cvar    then 'ruby-identifier'
+              when :on_gvar    then 'ruby-identifier'
+              when '=' != t[:text] && :on_op
+                               then 'ruby-operator'
+              when :on_tlambda then 'ruby-operator'
+              when :on_ident   then 'ruby-identifier'
+              when :on_label   then 'ruby-value'
+              when :on_backref, :on_dstring
+                               then 'ruby-node'
+              when :on_comment then 'ruby-comment'
+              when :on_embdoc  then 'ruby-comment'
+              when :on_regexp  then 'ruby-regexp'
+              when :on_tstring then 'ruby-string'
+              when :on_int, :on_float,
+                   :on_rational, :on_imaginary,
+                   :on_heredoc,
+                   :on_symbol, :on_CHAR then 'ruby-value'
+              when :on_heredoc_beg, :on_heredoc_end
+                               then 'ruby-identifier'
               end
 
-      text = CGI.escapeHTML t.text
+      comment_with_nl = false
+      if :on_comment == t[:kind] or :on_embdoc == t[:kind] or :on_heredoc_end == t[:kind]
+        comment_with_nl = true if "\n" == t[:text][-1]
+        text = t[:text].rstrip
+      else
+        text = t[:text]
+      end
+
+      if :on_ident == t[:kind] && starting_title
+        starting_title = false
+        style = 'ruby-identifier ruby-title'
+      end
+
+      if :on_kw == t[:kind] and 'def' == t[:text]
+        starting_title = true
+      end
+
+      text = CGI.escapeHTML text
 
       if style then
-        "<span class=\"#{style}\">#{text}</span>"
+        "<span class=\"#{style}\">#{text}</span>#{"\n" if comment_with_nl}"
       else
         text
       end
@@ -56,11 +74,16 @@ module RDoc::TokenStream
   ##
   # Adds +tokens+ to the collected tokens
 
-  def add_tokens(*tokens)
-    tokens.flatten.each { |token| @token_stream << token }
+  def add_tokens(tokens)
+    @token_stream.concat(tokens)
   end
 
-  alias add_token add_tokens
+  ##
+  # Adds one +token+ to the collected tokens
+
+  def add_token(token)
+    @token_stream.push(token)
+  end
 
   ##
   # Starts collecting tokens
@@ -89,8 +112,7 @@ module RDoc::TokenStream
   # Returns a string representation of the token stream
 
   def tokens_to_s
-    token_stream.compact.map { |token| token.text }.join ''
+    (token_stream or return '').compact.map { |token| token[:text] }.join ''
   end
 
 end
-