rdoc 6.11.0 → 6.13.0

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
 
@@ -89,13 +90,6 @@ 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.
-
-  attr_accessor :viewer
-
   ##
   # When mixed-in to a class, this points to the Context in which it was originally defined.
 
@@ -141,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
@@ -217,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.
   #
@@ -301,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
 
   ##
@@ -331,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+.
   #
@@ -780,32 +694,39 @@ class RDoc::Generator::Darkfish
     template
   end
 
-  # Returns an excerpt of the content for usage in meta description tags
-  def excerpt(content)
-    text = case content
+  # :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
-      content.text
-    when RDoc::Markup::Document
-      # This case is for page files that are not markdown nor rdoc
-      # We convert them to markdown for now as it's easier to extract the text
-      formatter = RDoc::Markup::ToMarkdown.new
-      formatter.start_accepting
-      formatter.accept_document(content)
-      formatter.end_accepting
+      comment.text
     else
-      content
+      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
-    first_paragraph_match = text.match(/[A-Z][^\.:\/]+\./)
-    return text[0...150].gsub(/\n/, " ").squeeze(" ") unless first_paragraph_match
+    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 = first_paragraph_match.post_match.match(/[A-Z][^\.:\/]+\./)
+    second_paragraph = text.match(pattern, first_paragraph_match.end(0))
     extracted_text << " " << second_paragraph[0] if second_paragraph
 
-    extracted_text[0...150].gsub(/\n/, " ").squeeze(" ")
+    extracted_text[0...150].tr_s("\n", " ").squeeze(" ")
   end
 
   def generate_ancestor_list(ancestors, klass)
@@ -825,4 +746,67 @@ class RDoc::Generator::Darkfish
 
     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

data/lib/rdoc/generator/markup.rb

@@ -34,7 +34,7 @@ module RDoc::Generator::Markup
   def formatter
     return @formatter if defined? @formatter
 
-    options = @store.rdoc.options
+    options = @store.options
     this = RDoc::Context === self ? self : @parent
 
     @formatter = RDoc::Markup::ToHtmlCrossref.new options, this.path, this
@@ -147,7 +147,7 @@ class RDoc::TopLevel
   # command line option to set.
 
   def cvs_url
-    url = @store.rdoc.options.webcvs
+    url = @store.options.webcvs
 
     if /%s/ =~ url then
       url % @relative_name

data/lib/rdoc/generator/pot/message_extractor.rb

@@ -35,11 +35,11 @@ class RDoc::Generator::POT::MessageExtractor
       end
     end
 
-    klass.each_constant do |constant|
+    klass.constants.each do |constant|
       extract_text(constant.comment, constant.full_name)
     end
 
-    klass.each_attribute do |attribute|
+    klass.attributes.each do |attribute|
       extract_text(attribute.comment, attribute.full_name)
     end
 

data/lib/rdoc/generator/pot.rb

@@ -81,11 +81,6 @@ class RDoc::Generator::POT
     end
   end
 
-  # :nodoc:
-  def class_dir
-    nil
-  end
-
   private
   def extract_messages
     extractor = MessageExtractor.new(@store)

data/lib/rdoc/generator/template/darkfish/_sidebar_classes.rhtml

@@ -1,34 +1,5 @@
 <div id="classindex-section" class="nav-section">
   <h3>Class and Module Index</h3>
 
-  <%-
-  all_classes = @classes.group_by do |klass|
-    klass.full_name[/\A[^:]++(?:::[^:]++(?=::))*+(?=::[^:]*+\z)/]
-  end.delete_if do |_, klasses|
-    !klasses.any?(&:display?)
-  end
-  link = proc do |index_klass, display = index_klass.display?|
-    if display
-      -%><code><a href="<%= rel_prefix %>/<%= index_klass.path %>"><%= index_klass.name %></a></code><%-
-    else
-      -%><code><%= index_klass.name %></code><%-
-    end
-  end
-  if top = all_classes[nil]
-    solo = top.one? {|klass| klass.display?}
-    traverse = proc do |klasses| -%>
-  <ul class="link-list">
-      <%- klasses.uniq!(&:full_name) -%>
-      <%- klasses.each do |index_klass| -%>
-        <%- if children = all_classes[index_klass.full_name] -%>
-  <li><details<% if solo; solo = false %> open<% end %>><summary><% link.call(index_klass) %></summary>
-          <%- traverse.call(children) -%>
-  </ul></details>
-        <%- elsif index_klass.display? -%>
-  <li><% link.call(index_klass, true) %>
-        <%- end -%>
-      <%- end -%>
-    <%- end -%>
-    <%- traverse.call(top) -%>
-  <%- end -%>
+  <%= generate_class_index_content(@classes, rel_prefix) %>
 </div>

data/lib/rdoc/generator/template/darkfish/_sidebar_extends.rhtml

@@ -3,7 +3,7 @@
   <h3>Extended With Modules</h3>
 
   <ul class="link-list">
-    <%- klass.each_extend do |ext| -%>
+    <%- klass.extends.each do |ext| -%>
   <%- unless String === ext.module then -%>
     <li><a class="extend" href="<%= klass.aref_to ext.module.path %>"><%= ext.module.full_name %></a>
   <%- else -%>

data/lib/rdoc/generator/template/darkfish/_sidebar_includes.rhtml

@@ -3,7 +3,7 @@
   <h3>Included Modules</h3>
 
   <ul class="link-list">
-  <%- klass.each_include do |inc| -%>
+  <%- klass.includes.each do |inc| -%>
   <%- unless String === inc.module then -%>
     <li><a class="include" href="<%= klass.aref_to inc.module.path %>"><%= inc.module.full_name %></a>
   <%- else -%>

data/lib/rdoc/generator/template/darkfish/class.rhtml

@@ -18,6 +18,21 @@
 </nav>
 
 <main role="main" aria-labelledby="<%=h klass.aref %>">
+  <%# If nesting level is 1, breadcrumb list is not needed %>
+  <% if breadcrumb.size > 1 %>
+    <ol role="navigation" aria-label="breadcrumb" class="breadcrumb">
+      <% breadcrumb.each do |namespace| %>
+      <li>
+        <% if namespace[:self] %>
+        <span><%= namespace[:name] %></span>
+        <% else %>
+        <a href="<%= namespace[:path] %>"><%= namespace[:name] %></a><span>::</span>
+        <% end %>
+      </li>
+      <% end %>
+    </ol>
+  <% end %>
+
   <h1 id="<%=h klass.aref %>" class="anchor-link <%= klass.type %>">
     <%= klass.type %> <%= klass.full_name %>
   </h1>

data/lib/rdoc/generator/template/darkfish/css/rdoc.css

@@ -199,6 +199,19 @@ nav h3,
   font-size: 1em;
 }
 
+ol.breadcrumb {
+  display: flex;
+
+  padding: 0;
+  margin: 0 0 1em;
+}
+
+ol.breadcrumb li {
+  display: block;
+  list-style: none;
+  font-size: 125%;
+}
+
 nav ul,
 nav dl,
 nav p {

data/lib/rdoc/generator/template/darkfish/index.rhtml

@@ -7,6 +7,7 @@
     <%= render '_sidebar_search.rhtml' %>
   </div>
 
+  <%= render '_sidebar_table_of_contents.rhtml' if defined?(current) %>
   <%= render '_sidebar_pages.rhtml' %>
   <%= render '_sidebar_classes.rhtml' %>
 
@@ -14,10 +15,9 @@
 </nav>
 
 <main role="main">
-<%- if @options.main_page and
-      main_page = @files.find { |f| f.full_name == @options.main_page } then %>
-<%= main_page.description %>
+<%- if @main_page %>
+  <%= @main_page.description %>
 <%- else -%>
-<p>This is the API documentation for <%= h @title %>.
+  <p>This is the API documentation for <%= h @title %>.
 <%- end -%>
 </main>

data/lib/rdoc/markdown.kpeg

@@ -992,9 +992,8 @@ Strike = &{ strike? }
          "~~"
          { strike a.join }
 
-# TODO alt text support
-Image = "!" ( ExplicitLink | ReferenceLink ):a
-        { "rdoc-image:#{a[/\[(.*)\]/, 1]}" }
+Image = "!" ExplicitLinkWithLabel:a
+        { "rdoc-image:#{a[:link]}:#{a[:label]}" }
 
 Link =  ExplicitLink | ReferenceLink | AutoLink
 
@@ -1006,8 +1005,11 @@ ReferenceLinkDouble = Label:content < Spnl > !"[]" Label:label
 ReferenceLinkSingle = Label:content < (Spnl "[]")? >
                       { link_to content, content, text }
 
-ExplicitLink =  Label:l "(" @Sp Source:s Spnl Title @Sp ")"
-                { "{#{l}}[#{s}]" }
+ExplicitLink = ExplicitLinkWithLabel:a
+               { "{#{a[:label]}}[#{a[:link]}]" }
+
+ExplicitLinkWithLabel = Label:label "(" @Sp Source:link Spnl Title @Sp ")"
+                        { { label: label, link: link } }
 
 Source  = ( "<" < SourceContents > ">" | < SourceContents > )
           { text }