rdoc 6.12.0 → 6.14.1

data/lib/rdoc/comment.rb

@@ -53,7 +53,7 @@ class RDoc::Comment
   # Creates a new comment with +text+ that is found in the RDoc::TopLevel
   # +location+.
 
-  def initialize text = nil, location = nil, language = nil
+  def initialize(text = nil, location = nil, language = nil)
     @location = location
     @text     = text.nil? ? nil : text.dup
     @language = language
@@ -67,11 +67,11 @@ class RDoc::Comment
   #--
   # TODO deep copy @document
 
-  def initialize_copy copy # :nodoc:
+  def initialize_copy(copy) # :nodoc:
     @text = copy.text.dup
   end
 
-  def == other # :nodoc:
+  def ==(other) # :nodoc:
     self.class === other and
       other.text == @text and other.location == @location
   end
@@ -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,10 +116,7 @@ class RDoc::Comment
       @text.slice! all_start...all_stop
 
       seq.gsub!(/^\s*/, '')
-      method.call_seq = seq
     end
-
-    method
   end
 
   ##
@@ -132,7 +129,7 @@ class RDoc::Comment
   ##
   # HACK dubious
 
-  def encode! encoding
+  def encode!(encoding)
     @text = String.new @text, encoding: encoding
     self
   end
@@ -140,7 +137,7 @@ class RDoc::Comment
   ##
   # Sets the format of this comment and resets any parsed document
 
-  def format= format
+  def format=(format)
     @format = format
     @document = nil
   end
@@ -211,7 +208,7 @@ class RDoc::Comment
   #
   # An error is raised if the comment contains a document but no text.
 
-  def text= text
+  def text=(text)
     raise RDoc::Error, 'replacing document-only comment is not allowed' if
       @text.nil? and @document
 

data/lib/rdoc/cross_reference.rb

@@ -124,7 +124,7 @@ class RDoc::CrossReference
   # Allows cross-references to be created based on the given +context+
   # (RDoc::Context).
 
-  def initialize context
+  def initialize(context)
     @context = context
     @store   = context.store
 
@@ -134,7 +134,7 @@ class RDoc::CrossReference
   ##
   # Returns a method reference to +name+.
 
-  def resolve_method name
+  def resolve_method(name)
     ref = nil
 
     if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
@@ -187,7 +187,7 @@ class RDoc::CrossReference
   # returned.  If +name+ is escaped +name+ is returned.  If +name+ is not
   # found +text+ is returned.
 
-  def resolve name, text
+  def resolve(name, text)
     return @seen[name] if @seen.include? name
 
     ref = case name

data/lib/rdoc/encoding.rb

@@ -29,7 +29,7 @@ module RDoc::Encoding
   # If +force_transcode+ is true the document will be transcoded and any
   # unknown character in the target encoding will be replaced with '?'
 
-  def self.read_file filename, encoding, force_transcode = false
+  def self.read_file(filename, encoding, force_transcode = false)
     content = File.open filename, "rb" do |f| f.read end
     content.gsub!("\r\n", "\n") if RUBY_PLATFORM =~ /mswin|mingw/
 
@@ -89,7 +89,7 @@ module RDoc::Encoding
   ##
   # Detects the encoding of +string+ based on the magic comment
 
-  def self.detect_encoding string
+  def self.detect_encoding(string)
     result = HEADER_REGEXP.match string
     name = result && result[:name]
 
@@ -99,7 +99,7 @@ module RDoc::Encoding
   ##
   # Removes magic comments and shebang
 
-  def self.remove_magic_comment string
+  def self.remove_magic_comment(string)
     string.sub HEADER_REGEXP do |s|
       s.gsub(/[^\n]/, '')
     end
@@ -109,7 +109,7 @@ module RDoc::Encoding
   # Changes encoding based on +encoding+ without converting and returns new
   # string
 
-  def self.change_encoding text, encoding
+  def self.change_encoding(text, encoding)
     if text.kind_of? RDoc::Comment
       text.encode! encoding
     else

data/lib/rdoc/erb_partial.rb

@@ -9,7 +9,7 @@ class RDoc::ERBPartial < ERB
   # Overrides +compiler+ startup to set the +eoutvar+ to an empty string only
   # if it isn't already set.
 
-  def set_eoutvar compiler, eoutvar = '_erbout'
+  def set_eoutvar(compiler, eoutvar = '_erbout')
     super
 
     compiler.pre_cmd = ["#{eoutvar} ||= +''"]

data/lib/rdoc/erbio.rb

@@ -20,14 +20,14 @@ class RDoc::ERBIO < ERB
   ##
   # Defaults +eoutvar+ to 'io', otherwise is identical to ERB's initialize
 
-  def initialize str, trim_mode: nil, eoutvar: 'io'
+  def initialize(str, trim_mode: nil, eoutvar: 'io')
     super(str, trim_mode: trim_mode, eoutvar: eoutvar)
   end
 
   ##
   # Instructs +compiler+ how to write to +io_variable+
 
-  def set_eoutvar compiler, io_variable
+  def set_eoutvar(compiler, io_variable)
     compiler.put_cmd    = "#{io_variable}.write"
     compiler.insert_cmd = "#{io_variable}.write"
     compiler.pre_cmd    = []

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
 
@@ -156,7 +150,7 @@ class RDoc::Generator::Darkfish
   ##
   # Initialize a few instance variables before we start
 
-  def initialize store, options
+  def initialize(store, options)
     @store   = store
     @options = options
 
@@ -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.
@@ -291,7 +269,7 @@ class RDoc::Generator::Darkfish
   # Return a list of the documented modules sorted by salience first, then
   # by name.
 
-  def get_sorted_module_list classes
+  def get_sorted_module_list(classes)
     classes.select do |klass|
       klass.display?
     end.sort
@@ -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?
 
@@ -337,9 +313,7 @@ class RDoc::Generator::Darkfish
   ##
   # Generates a class file for +klass+
 
-  def generate_class klass, template_file = nil
-    setup
-
+  def generate_class(klass, template_file = nil)
     current = klass
 
     template_file ||= @template_dir + 'class.rhtml'
@@ -351,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}"
 
@@ -360,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
@@ -369,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?
@@ -396,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'
 
@@ -464,9 +435,7 @@ class RDoc::Generator::Darkfish
   ##
   # Generate a page file for +file+
 
-  def generate_page file
-    setup
-
+  def generate_page(file)
     template_file = @template_dir + 'page.rhtml'
 
     out_file = @outputdir + file.path
@@ -493,9 +462,7 @@ class RDoc::Generator::Darkfish
   ##
   # Generates the 404 page for the RDoc servlet
 
-  def generate_servlet_not_found message
-    setup
-
+  def generate_servlet_not_found(message)
     template_file = @template_dir + 'servlet_not_found.rhtml'
     return unless template_file.exist?
 
@@ -526,9 +493,7 @@ class RDoc::Generator::Darkfish
   ##
   # Generates the servlet root page for the RDoc servlet
 
-  def generate_servlet_root installed
-    setup
-
+  def generate_servlet_root(installed)
     template_file = @template_dir + 'servlet_root.rhtml'
     return unless template_file.exist?
 
@@ -554,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?
 
@@ -584,7 +547,7 @@ class RDoc::Generator::Darkfish
     raise error
   end
 
-  def install_rdoc_static_file source, destination, options # :nodoc:
+  def install_rdoc_static_file(source, destination, options) # :nodoc:
     return unless source.exist?
 
     begin
@@ -617,65 +580,13 @@ 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+.
   #
   # For backwards compatibility, if +body_file+ contains "<html" the body is
   # used directly.
 
-  def assemble_template body_file
+  def assemble_template(body_file)
     body = body_file.read
     return body if body =~ /<html/
 
@@ -684,7 +595,7 @@ class RDoc::Generator::Darkfish
     <<-TEMPLATE
 <!DOCTYPE html>
 
-<html>
+<html lang="#{@options.locale&.name || 'en'}">
 <head>
 #{head_file.read}
 
@@ -696,7 +607,7 @@ class RDoc::Generator::Darkfish
   # Renders the ERb contained in +file_name+ relative to the template
   # directory and returns the result based on the current context.
 
-  def render file_name
+  def render(file_name)
     template_file = @template_dir + file_name
 
     template = template_for template_file, false, RDoc::ERBPartial
@@ -714,7 +625,7 @@ class RDoc::Generator::Darkfish
   #
   # An io will be yielded which must be captured by binding in the caller.
 
-  def render_template template_file, out_file = nil # :yield: io
+  def render_template(template_file, out_file = nil) # :yield: io
     io_output = out_file && !@dry_run && @file_output
     erb_klass = io_output ? RDoc::ERBIO : ERB
 
@@ -748,7 +659,7 @@ class RDoc::Generator::Darkfish
   # Creates the result for +template+ with +context+.  If an error is raised a
   # Pathname +template_file+ will indicate the file where the error occurred.
 
-  def template_result template, context, template_file
+  def template_result(template, context, template_file)
     template.filename = template_file.to_s
     template.result context
   rescue NoMethodError => e
@@ -761,7 +672,7 @@ class RDoc::Generator::Darkfish
   ##
   # Retrieves a cache template for +file+, if present, or fills the cache.
 
-  def template_for file, page = true, klass = ERB
+  def template_for(file, page = true, klass = ERB)
     template = @template_cache[file]
 
     return template if template
@@ -783,6 +694,12 @@ 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
@@ -794,14 +711,22 @@ class RDoc::Generator::Darkfish
 
     # 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)
@@ -821,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,12 +86,10 @@ 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
+  def initialize(parent_generator, options)
     @parent_generator = parent_generator
     @store            = parent_generator.store
     @options          = options
@@ -265,21 +263,7 @@ 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:
+  def reset(files, classes) # :nodoc:
     @files   = files
     @classes = classes
 
@@ -293,7 +277,7 @@ class RDoc::Generator::JsonIndex
   ##
   # Removes whitespace and downcases +string+
 
-  def search_string string
+  def search_string(string)
     string.downcase.gsub(/\s/, '')
   end
 

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
@@ -55,6 +55,18 @@ module RDoc::Generator::Markup
     end
   end
 
+  ##
+  # The preferred URL for this object.
+
+  def canonical_url
+    options = @store.options
+    if path
+      File.join(options.canonical_root, path.to_s)
+    else
+      options.canonical_root
+    end
+  end
+
 end
 
 class RDoc::CodeObject
@@ -147,7 +159,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

@@ -7,7 +7,7 @@ class RDoc::Generator::POT::MessageExtractor
   ##
   # Creates a message extractor for +store+.
 
-  def initialize store
+  def initialize(store)
     @store = store
     @po = RDoc::Generator::POT::PO.new
   end
@@ -25,7 +25,7 @@ class RDoc::Generator::POT::MessageExtractor
 
   private
 
-  def extract_from_klass klass
+  def extract_from_klass(klass)
     extract_text(klass.comment_location, klass.full_name)
 
     klass.each_section do |section, constants, attributes|
@@ -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
 
@@ -48,7 +48,7 @@ class RDoc::Generator::POT::MessageExtractor
     end
   end
 
-  def extract_text text, comment, location = nil
+  def extract_text(text, comment, location = nil)
     return if text.nil?
 
     options = {
@@ -61,7 +61,7 @@ class RDoc::Generator::POT::MessageExtractor
     end
   end
 
-  def entry msgid, options
+  def entry(msgid, options)
     RDoc::Generator::POT::POEntry.new(msgid, options)
   end
 

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

@@ -15,7 +15,7 @@ class RDoc::Generator::POT::PO
   ##
   # Adds a PO entry to the PO.
 
-  def add entry
+  def add(entry)
     existing_entry = @entries[entry.msgid]
     if existing_entry
       entry = existing_entry.merge(entry)