rdoc 6.7.0 → 6.13.1

data/lib/rdoc/{method_attr.rb → code_object/method_attr.rb}

@@ -63,19 +63,13 @@ class RDoc::MethodAttr < RDoc::CodeObject
 
   attr_reader :arglists
 
-  ##
-  # Pretty parameter list for this method
-
-  attr_reader :param_seq
-
-
   ##
   # Creates a new MethodAttr from token stream +text+ and method or attribute
   # name +name+.
   #
   # Usually this is called by super from a subclass.
 
-  def initialize text, name
+  def initialize(text, name, singleton: false)
     super()
 
     @text = text
@@ -84,14 +78,13 @@ class RDoc::MethodAttr < RDoc::CodeObject
     @aliases      = []
     @is_alias_for = nil
     @parent_name  = nil
-    @singleton    = nil
+    @singleton    = singleton
     @visibility   = :public
     @see = false
 
     @arglists     = nil
     @block_params = nil
     @call_seq     = nil
-    @param_seq    = nil
     @params       = nil
   end
 
@@ -114,8 +107,8 @@ class RDoc::MethodAttr < RDoc::CodeObject
     return unless other.respond_to?(:singleton) &&
                   other.respond_to?(:name)
 
-    [     @singleton ? 0 : 1,       name] <=>
-    [other.singleton ? 0 : 1, other.name]
+    [@singleton      ? 0 : 1, name_ord_range,       name] <=>
+    [other.singleton ? 0 : 1, other.name_ord_range, other.name]
   end
 
   def == other # :nodoc:
@@ -268,8 +261,8 @@ class RDoc::MethodAttr < RDoc::CodeObject
       when 'const_get' then 'const'
       when 'new' then
         $1.split('::').last.  # ClassName => class_name
-          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-          gsub(/([a-z\d])([A-Z])/,'\1_\2').
+          gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
+          gsub(/([a-z\d])([A-Z])/, '\1_\2').
           downcase
       else
         $2
@@ -291,7 +284,7 @@ class RDoc::MethodAttr < RDoc::CodeObject
   def html_name
     require 'cgi/util'
 
-    CGI.escape(@name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
+    CGI.escape(@name.gsub('-', '-2D')).gsub('%', '-').sub(/^-/, '')
   end
 
   ##
@@ -320,19 +313,6 @@ class RDoc::MethodAttr < RDoc::CodeObject
     @singleton ? '::' : '#'
   end
 
-  ##
-  # Name for output to HTML.  For class methods the full name with a "." is
-  # used like +SomeClass.method_name+.  For instance methods the class name is
-  # used if +context+ does not match the parent.
-  #
-  # This is to help prevent people from using :: to call class methods.
-
-  def output_name context
-    return "#{name_prefix}#{@name}" if context == parent
-
-    "#{parent_name}#{@singleton ? '.' : '#'}#{@name}"
-  end
-
   ##
   # Method/attribute name with class/instance indicator
 
@@ -415,4 +395,16 @@ class RDoc::MethodAttr < RDoc::CodeObject
     end
   end
 
+  def name_ord_range # :nodoc:
+    case name.ord
+    when 0..64 # anything below "A"
+      1
+    when 91..96 # the symbols between "Z" and "a"
+      2
+    when 123..126 # 7-bit symbols above "z": "{", "|", "}", "~"
+      3
+    else # everythig else can be sorted as normal
+      4
+    end
+  end
 end

data/lib/rdoc/{require.rb → code_object/require.rb}

@@ -24,7 +24,7 @@ class RDoc::Require < RDoc::CodeObject
       self.class,
       object_id,
       @name,
-      parent_file_name,
+      @parent ? @parent.base_name : '(unknown)'
     ]
   end
 

data/lib/rdoc/{top_level.rb → code_object/top_level.rb}

@@ -6,11 +6,6 @@ class RDoc::TopLevel < RDoc::Context
 
   MARSHAL_VERSION = 0 # :nodoc:
 
-  ##
-  # This TopLevel's File::Stat struct
-
-  attr_accessor :file_stat
-
   ##
   # Relative name of this file
 
@@ -28,8 +23,6 @@ class RDoc::TopLevel < RDoc::Context
 
   attr_reader :classes_or_modules
 
-  attr_accessor :diagram # :nodoc:
-
   ##
   # The parser class that processed this file
 
@@ -45,8 +38,6 @@ class RDoc::TopLevel < RDoc::Context
     @name = nil
     @absolute_name = absolute_name
     @relative_name = relative_name
-    @file_stat     = File.stat(absolute_name) rescue nil # HACK for testing
-    @diagram       = nil
     @parser        = nil
 
     @classes_or_modules = []
@@ -173,28 +164,19 @@ class RDoc::TopLevel < RDoc::Context
   ##
   # URL for this with a +prefix+
 
-  def http_url(prefix)
-    path = [prefix, @relative_name.tr('.', '_')]
-
-    File.join(*path.compact) + '.html'
+  def http_url
+    @relative_name.tr('.', '_') + '.html'
   end
 
   def inspect # :nodoc:
     "#<%s:0x%x %p modules: %p classes: %p>" % [
       self.class, object_id,
       base_name,
-      @modules.map { |n,m| m },
-      @classes.map { |n,c| c }
+      @modules.map { |n, m| m },
+      @classes.map { |n, c| c }
     ]
   end
 
-  ##
-  # Time this file was last modified, if known
-
-  def last_modified
-    @file_stat ? file_stat.mtime : nil
-  end
-
   ##
   # Dumps this TopLevel for use by ri.  See also #marshal_load
 
@@ -214,9 +196,7 @@ class RDoc::TopLevel < RDoc::Context
     initialize array[1]
 
     @parser  = array[2]
-    @comment = array[3]
-
-    @file_stat          = nil
+    @comment = RDoc::Comment.from_document array[3]
   end
 
   ##
@@ -246,7 +226,9 @@ class RDoc::TopLevel < RDoc::Context
   # Path to this file for use with HTML generator output.
 
   def path
-    http_url @store.rdoc.generator.file_dir
+    prefix = options.file_path_prefix
+    return http_url unless prefix
+    File.join(prefix, http_url)
   end
 
   def pretty_print q # :nodoc:
@@ -254,8 +236,8 @@ class RDoc::TopLevel < RDoc::Context
       q.text "base name: #{base_name.inspect}"
       q.breakable
 
-      items = @modules.map { |n,m| m }
-      items.concat @modules.map { |n,c| c }
+      items = @modules.map { |n, m| m }
+      items.concat @modules.map { |n, c| c }
       q.seplist items do |mod| q.pp mod end
     end
   end

data/lib/rdoc/code_object.rb

@@ -21,9 +21,10 @@
 #     * RDoc::MetaMethod
 # * RDoc::Alias
 # * RDoc::Constant
+# * RDoc::Require
 # * RDoc::Mixin
-#   * RDoc::Require
 #   * RDoc::Include
+#   * RDoc::Extend
 
 class RDoc::CodeObject
 
@@ -90,11 +91,9 @@ class RDoc::CodeObject
   attr_reader :store
 
   ##
-  # We are the model of the code, but we know that at some point we will be
-  # worked on by viewers. By implementing the Viewable protocol, viewers can
-  # associated themselves with these objects.
+  # When mixed-in to a class, this points to the Context in which it was originally defined.
 
-  attr_accessor :viewer
+  attr_accessor :mixin_from
 
   ##
   # Creates a new CodeObject that will document itself and its children
@@ -111,6 +110,7 @@ class RDoc::CodeObject
     @full_name        = nil
     @store            = nil
     @track_visibility = true
+    @mixin_from       = nil
 
     initialize_visibility
   end
@@ -135,7 +135,6 @@ class RDoc::CodeObject
   def comment=(comment)
     @comment = case comment
                when NilClass               then ''
-               when RDoc::Markup::Document then comment
                when RDoc::Comment          then comment.normalize
                else
                  if comment and not comment.empty? then
@@ -211,20 +210,6 @@ class RDoc::CodeObject
     @document_children = @document_self
   end
 
-  ##
-  # Yields each parent of this CodeObject.  See also
-  # RDoc::ClassModule#each_ancestor
-
-  def each_parent
-    code_object = self
-
-    while code_object = code_object.parent do
-      yield code_object
-    end
-
-    self
-  end
-
   ##
   # File name where this CodeObject was found.
   #
@@ -295,11 +280,7 @@ class RDoc::CodeObject
   # This is used by Text#snippet
 
   def options
-    if @store and @store.rdoc then
-      @store.rdoc.options
-    else
-      RDoc::Options.new
-    end
+    @store&.options || RDoc::Options.new
   end
 
   ##
@@ -325,13 +306,6 @@ class RDoc::CodeObject
     end
   end
 
-  ##
-  # File name of our parent
-
-  def parent_file_name
-    @parent ? @parent.base_name : '(unknown)'
-  end
-
   ##
   # Name of our parent
 

data/lib/rdoc/comment.rb

@@ -92,7 +92,7 @@ class RDoc::Comment
   #   #   ARGF.to_a(limit)      -> array
   #   #   ARGF.to_a(sep, limit) -> array
 
-  def extract_call_seq method
+  def extract_call_seq
     # we must handle situations like the above followed by an unindented first
     # comment.  The difficulty is to make sure not to match lines starting
     # with ARGF at the same indent, but that are after the first description
@@ -116,17 +116,14 @@ class RDoc::Comment
       @text.slice! all_start...all_stop
 
       seq.gsub!(/^\s*/, '')
-      method.call_seq = seq
     end
-
-    method
   end
 
   ##
   # A comment is empty if its text String is empty.
 
   def empty?
-    @text.empty?
+    @text.empty? && (@document.nil? || @document.empty?)
   end
 
   ##
@@ -226,4 +223,14 @@ class RDoc::Comment
     @format == 'tomdoc'
   end
 
+  ##
+  # Create a new parsed comment from a document
+
+  def self.from_document(document) # :nodoc:
+    comment = RDoc::Comment.new('')
+    comment.document = document
+    comment.location = RDoc::TopLevel.new(document.file) if document.file
+    comment
+  end
+
 end

data/lib/rdoc/generator/darkfish.rb

@@ -73,12 +73,6 @@ class RDoc::Generator::Darkfish
       css/rdoc.css
   ]
 
-  ##
-  # Path to this file's parent directory. Used to find templates and other
-  # resources.
-
-  GENERATOR_DIR = File.join 'rdoc', 'generator'
-
   ##
   # Release Version
 
@@ -184,22 +178,6 @@ class RDoc::Generator::Darkfish
     $stderr.puts(*msg)
   end
 
-  ##
-  # Directory where generated class HTML files live relative to the output
-  # dir.
-
-  def class_dir
-    nil
-  end
-
-  ##
-  # Directory where generated class HTML files live relative to the output
-  # dir.
-
-  def file_dir
-    nil
-  end
-
   ##
   # Create the directories the generated docs will live in if they don't
   # already exist.
@@ -301,8 +279,6 @@ class RDoc::Generator::Darkfish
   # Generate an index page which lists all the classes which are documented.
 
   def generate_index
-    setup
-
     template_file = @template_dir + 'index.rhtml'
     return unless template_file.exist?
 
@@ -316,11 +292,14 @@ class RDoc::Generator::Darkfish
     asset_rel_prefix = rel_prefix + @asset_rel_path
 
     @title = @options.title
+    @main_page = @files.find { |f| f.full_name == @options.main_page }
 
     render_template template_file, out_file do |io|
       here = binding
       # suppress 1.9.3 warning
       here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
+      # some partials rely on the presence of current variable to render
+      here.local_variable_set(:current, @main_page) if @main_page
       here
     end
   rescue => e
@@ -335,8 +314,6 @@ class RDoc::Generator::Darkfish
   # Generates a class file for +klass+
 
   def generate_class klass, template_file = nil
-    setup
-
     current = klass
 
     template_file ||= @template_dir + 'class.rhtml'
@@ -348,7 +325,9 @@ class RDoc::Generator::Darkfish
     search_index_rel_prefix += @asset_rel_path if @file_output
 
     asset_rel_prefix = rel_prefix + @asset_rel_path
-    svninfo          = get_svninfo(current)
+
+    breadcrumb = # used in templates
+    breadcrumb = generate_nesting_namespaces_breadcrumb(current, rel_prefix)
 
     @title = "#{klass.type} #{klass.full_name} - #{@options.title}"
 
@@ -357,7 +336,6 @@ class RDoc::Generator::Darkfish
       here = binding
       # suppress 1.9.3 warning
       here.local_variable_set(:asset_rel_prefix, asset_rel_prefix)
-      here.local_variable_set(:svninfo, svninfo)
       here
     end
   end
@@ -366,8 +344,6 @@ class RDoc::Generator::Darkfish
   # Generate a documentation file for each class and module
 
   def generate_class_files
-    setup
-
     template_file = @template_dir + 'class.rhtml'
     template_file = @template_dir + 'classpage.rhtml' unless
       template_file.exist?
@@ -393,8 +369,6 @@ class RDoc::Generator::Darkfish
   # Generate a documentation file for each file
 
   def generate_file_files
-    setup
-
     page_file     = @template_dir + 'page.rhtml'
     fileinfo_file = @template_dir + 'fileinfo.rhtml'
 
@@ -462,8 +436,6 @@ class RDoc::Generator::Darkfish
   # Generate a page file for +file+
 
   def generate_page file
-    setup
-
     template_file = @template_dir + 'page.rhtml'
 
     out_file = @outputdir + file.path
@@ -491,8 +463,6 @@ class RDoc::Generator::Darkfish
   # Generates the 404 page for the RDoc servlet
 
   def generate_servlet_not_found message
-    setup
-
     template_file = @template_dir + 'servlet_not_found.rhtml'
     return unless template_file.exist?
 
@@ -524,8 +494,6 @@ class RDoc::Generator::Darkfish
   # Generates the servlet root page for the RDoc servlet
 
   def generate_servlet_root installed
-    setup
-
     template_file = @template_dir + 'servlet_root.rhtml'
     return unless template_file.exist?
 
@@ -551,8 +519,6 @@ class RDoc::Generator::Darkfish
   # Generate an index page which lists all the classes which are documented.
 
   def generate_table_of_contents
-    setup
-
     template_file = @template_dir + 'table_of_contents.rhtml'
     return unless template_file.exist?
 
@@ -614,58 +580,6 @@ class RDoc::Generator::Darkfish
     @modsort = get_sorted_module_list @classes
   end
 
-  ##
-  # Return a string describing the amount of time in the given number of
-  # seconds in terms a human can understand easily.
-
-  def time_delta_string seconds
-    return 'less than a minute'          if seconds < 60
-    return "#{seconds / 60} minute#{seconds / 60 == 1 ? '' : 's'}" if
-                                            seconds < 3000     # 50 minutes
-    return 'about one hour'              if seconds < 5400     # 90 minutes
-    return "#{seconds / 3600} hours"     if seconds < 64800    # 18 hours
-    return 'one day'                     if seconds < 86400    #  1 day
-    return 'about one day'               if seconds < 172800   #  2 days
-    return "#{seconds / 86400} days"     if seconds < 604800   #  1 week
-    return 'about one week'              if seconds < 1209600  #  2 week
-    return "#{seconds / 604800} weeks"   if seconds < 7257600  #  3 months
-    return "#{seconds / 2419200} months" if seconds < 31536000 #  1 year
-    return "#{seconds / 31536000} years"
-  end
-
-  # %q$Id: darkfish.rb 52 2009-01-07 02:08:11Z deveiant $"
-  SVNID_PATTERN = /
-    \$Id:\s
-    (\S+)\s                # filename
-    (\d+)\s                # rev
-    (\d{4}-\d{2}-\d{2})\s  # Date (YYYY-MM-DD)
-    (\d{2}:\d{2}:\d{2}Z)\s # Time (HH:MM:SSZ)
-    (\w+)\s                # committer
-    \$$
-  /x
-
-  ##
-  # Try to extract Subversion information out of the first constant whose
-  # value looks like a subversion Id tag. If no matching constant is found,
-  # and empty hash is returned.
-
-  def get_svninfo klass
-    constants = klass.constants or return {}
-
-    constants.find { |c| c.value =~ SVNID_PATTERN } or return {}
-
-    filename, rev, date, time, committer = $~.captures
-    commitdate = Time.parse "#{date} #{time}"
-
-    return {
-      :filename    => filename,
-      :rev         => Integer(rev),
-      :commitdate  => commitdate,
-      :commitdelta => time_delta_string(Time.now - commitdate),
-      :committer   => committer,
-    }
-  end
-
   ##
   # Creates a template from its components and the +body_file+.
   #
@@ -677,7 +591,6 @@ class RDoc::Generator::Darkfish
     return body if body =~ /<html/
 
     head_file = @template_dir + '_head.rhtml'
-    footer_file = @template_dir + '_footer.rhtml'
 
     <<-TEMPLATE
 <!DOCTYPE html>
@@ -687,8 +600,6 @@ class RDoc::Generator::Darkfish
 #{head_file.read}
 
 #{body}
-
-#{footer_file.read}
     TEMPLATE
   end
 
@@ -783,4 +694,119 @@ class RDoc::Generator::Darkfish
     template
   end
 
+  # :stopdoc:
+  ParagraphExcerptRegexpOther = %r[\b\w[^./:]++\.]
+  # use \p/\P{letter} instead of \w/\W in Unicode
+  ParagraphExcerptRegexpUnicode = %r[\b\p{letter}[^./:]++\.]
+  # :startdoc:
+
+  # Returns an excerpt of the comment for usage in meta description tags
+  def excerpt(comment)
+    text = case comment
+    when RDoc::Comment
+      comment.text
+    else
+      comment
+    end
+
+    # Match from a capital letter to the first period, discarding any links, so
+    # that we don't end up matching badges in the README
+    pattern = ParagraphExcerptRegexpUnicode
+    begin
+      first_paragraph_match = text.match(pattern)
+    rescue Encoding::CompatibilityError
+      # The doc is non-ASCII text and encoded in other than Unicode base encodings.
+      raise if pattern == ParagraphExcerptRegexpOther
+      pattern = ParagraphExcerptRegexpOther
+      retry
+    end
+    return text[0...150].tr_s("\n", " ").squeeze(" ") unless first_paragraph_match
+
+    extracted_text = first_paragraph_match[0]
+    second_paragraph = text.match(pattern, first_paragraph_match.end(0))
+    extracted_text << " " << second_paragraph[0] if second_paragraph
+
+    extracted_text[0...150].tr_s("\n", " ").squeeze(" ")
+  end
+
+  def generate_ancestor_list(ancestors, klass)
+    return '' if ancestors.empty?
+
+    ancestor = ancestors.shift
+    content = +'<ul><li>'
+
+    if ancestor.is_a?(RDoc::NormalClass)
+      content << "<a href=\"#{klass.aref_to ancestor.path}\">#{ancestor.full_name}</a>"
+    else
+      content << ancestor.to_s
+    end
+
+    # Recursively call the method for the remaining ancestors
+    content << generate_ancestor_list(ancestors, klass)
+
+    content << '</li></ul>'
+  end
+
+  def generate_class_link(klass, rel_prefix)
+    if klass.display?
+      %(<code><a href="#{rel_prefix}/#{klass.path}">#{klass.name}</a></code>)
+    else
+      %(<code>#{klass.name}</code>)
+    end
+  end
+
+  def generate_class_index_content(classes, rel_prefix)
+    grouped_classes = group_classes_by_namespace_for_sidebar(classes)
+    return '' unless top = grouped_classes[nil]
+
+    solo = top.one? { |klass| klass.display? }
+    traverse_classes(top, grouped_classes, rel_prefix, solo)
+  end
+
+  def traverse_classes(klasses, grouped_classes, rel_prefix, solo = false)
+    content = +'<ul class="link-list">'
+
+    klasses.each do |index_klass|
+      if children = grouped_classes[index_klass.full_name]
+        content << %(<li><details#{solo ? ' open' : ''}><summary>#{generate_class_link(index_klass, rel_prefix)}</summary>)
+        content << traverse_classes(children, grouped_classes, rel_prefix)
+        content << '</details></li>'
+        solo = false
+      elsif index_klass.display?
+        content << %(<li>#{generate_class_link(index_klass, rel_prefix)}</li>)
+      end
+    end
+
+    "#{content}</ul>"
+  end
+
+  def group_classes_by_namespace_for_sidebar(classes)
+    grouped_classes = classes.group_by do |klass|
+      klass.full_name[/\A[^:]++(?:::[^:]++(?=::))*+(?=::[^:]*+\z)/]
+    end.select do |_, klasses|
+      klasses.any?(&:display?)
+    end
+
+    grouped_classes.values.each(&:uniq!)
+    grouped_classes
+  end
+
+  private
+
+  def nesting_namespaces_to_class_modules klass
+    tree = {}
+
+    klass.nesting_namespaces.zip(klass.fully_qualified_nesting_namespaces) do |ns, fqns|
+      tree[ns] = @store.classes_hash[fqns] || @store.modules_hash[fqns]
+    end
+
+    tree
+  end
+
+  def generate_nesting_namespaces_breadcrumb klass, rel_prefix
+    nesting_namespaces_to_class_modules(klass).map do |namespace, class_module|
+      path = class_module ? (rel_prefix + class_module.path).to_s : ""
+      { name: namespace, path: path, self: klass.full_name == class_module&.full_name }
+    end
+  end
 end

data/lib/rdoc/generator/json_index.rb

@@ -86,9 +86,7 @@ class RDoc::Generator::JsonIndex
   attr_reader :index # :nodoc:
 
   ##
-  # Creates a new generator.  +parent_generator+ is used to determine the
-  # class_dir and file_dir of links in the output index.
-  #
+  # Creates a new generator.
   # +options+ are the same options passed to the parent generator.
 
   def initialize parent_generator, options
@@ -265,20 +263,6 @@ class RDoc::Generator::JsonIndex
     end
   end
 
-  ##
-  # The directory classes are written to
-
-  def class_dir
-    @parent_generator.class_dir
-  end
-
-  ##
-  # The directory files are written to
-
-  def file_dir
-    @parent_generator.file_dir
-  end
-
   def reset files, classes # :nodoc:
     @files   = files
     @classes = classes