rdoc 5.1.0 → 6.13.1

data/TODO.rdoc

@@ -1,9 +1,10 @@
+= TODO
 This file contains some things that might happen in RDoc, or might not.
 Forward Looking Statements applies.
 
-=== RDoc::VERSION.succ
+== RDoc::VERSION.succ
 
-Blockers:
+=== Blockers:
 
 * Update LICENSE to match ruby's switch
 * The alias keyword should not be bidirectional
@@ -13,7 +14,7 @@ Blockers:
 * Fix consumption of , after link like: RDoc[rdoc-ref:RDoc], <- comma here
 * Remove support for links like Matrix[*rows]
 
-Nice to have:
+=== Nice to have:
 
 * Parse only changed files (like in ruby)
 * Page of Glory (or Shame) in HTML output showing documentation coverage
@@ -26,9 +27,9 @@ Nice to have:
 * Global variable support
 * Provide the code_object to directive handlers
 
-=== 4
+== More Future
 
-API changes to RDoc
+=== API changes to RDoc
 
 * RDoc::TopLevel#add_method should automatically create the appropriate method
   class rather than requiring one be passed in.
@@ -36,7 +37,7 @@ API changes to RDoc
 * Add versions to RDoc::Markup syntax tree marshal format
 * Comments can no longer be Strings
 
-=== Crazy Ideas
+== Crazy Ideas
 
 * Auto-normalize heading levels to look OK.  It's weird to see an <h1> in
   the middle of a method section.
@@ -46,7 +47,7 @@ API changes to RDoc
   * Rename Context to Container
   * Rename NormalClass to Class
 
-=== Accessibility
+== Accessibility
 
 Page title in right hand side
 

data/exe/rdoc

@@ -41,4 +41,3 @@ rescue Exception => e
 
   exit 1
 end
-

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

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # Represent an alias, which is an old_name/new_name pair associated with a
 # particular context
@@ -23,7 +23,7 @@ class RDoc::Alias < RDoc::CodeObject
   ##
   # Is this an alias declared in a singleton context?
 
-  attr_accessor :singleton
+  attr_reader :singleton
 
   ##
   # Source file token stream
@@ -34,7 +34,7 @@ class RDoc::Alias < RDoc::CodeObject
   # Creates a new Alias with a token stream of +text+ that aliases +old_name+
   # to +new_name+, has +comment+ and is a +singleton+ context.
 
-  def initialize(text, old_name, new_name, comment, singleton = false)
+  def initialize(text, old_name, new_name, comment, singleton: false)
     super()
 
     @text = text
@@ -59,18 +59,11 @@ class RDoc::Alias < RDoc::CodeObject
     "#alias-#{type}-#{html_name}"
   end
 
-  ##
-  # Full old name including namespace
-
-  def full_old_name
-    @full_name || "#{parent.name}#{pretty_old_name}"
-  end
-
   ##
   # HTML id-friendly version of +#new_name+.
 
   def html_name
-    CGI.escape(@new_name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
+    CGI.escape(@new_name.gsub('-', '-2D')).gsub('%', '-').sub(/^-/, '')
   end
 
   def inspect # :nodoc:
@@ -109,4 +102,3 @@ class RDoc::Alias < RDoc::CodeObject
   end
 
 end
-

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

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # An anonymous class like:
 #
@@ -8,4 +8,3 @@
 
 class RDoc::AnonClass < RDoc::ClassModule
 end
-

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

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # AnyMethod is the base class for objects representing methods
 
@@ -26,15 +26,8 @@ class RDoc::AnyMethod < RDoc::MethodAttr
 
   attr_accessor :c_function
 
-  ##
-  # Different ways to call this method
-
-  attr_reader :call_seq
-
-  ##
-  # Parameters for this method
-
-  attr_accessor :params
+  # The section title of the method (if defined in a C file via +:category:+)
+  attr_accessor :section_title
 
   ##
   # If true this method uses +super+ to call a superclass version
@@ -46,8 +39,8 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   ##
   # Creates a new AnyMethod with a token stream +text+ and +name+
 
-  def initialize text, name
-    super
+  def initialize(text, name, singleton: false)
+    super(text, name, singleton: singleton)
 
     @c_function = nil
     @dont_rename_initialize = false
@@ -60,10 +53,9 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   # Adds +an_alias+ as an alias for this method in +context+.
 
   def add_alias an_alias, context = nil
-    method = self.class.new an_alias.text, an_alias.new_name
+    method = self.class.new an_alias.text, an_alias.new_name, singleton: singleton
 
     method.record_location an_alias.file
-    method.singleton = self.singleton
     method.params = self.params
     method.visibility = self.visibility
     method.comment = an_alias.comment
@@ -93,6 +85,19 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     end
   end
 
+  ##
+  # Different ways to call this method
+
+  def call_seq
+    unless call_seq = _call_seq
+      call_seq = is_alias_for._call_seq if is_alias_for
+    end
+
+    return unless call_seq
+
+    deduplicate_call_seq(call_seq)
+  end
+
   ##
   # Sets the different ways you can call this method.  If an empty +call_seq+
   # is given nil is assumed.
@@ -100,11 +105,18 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   # See also #param_seq
 
   def call_seq= call_seq
-    return if call_seq.empty?
+    return if call_seq.nil? || call_seq.empty?
 
     @call_seq = call_seq
   end
 
+  ##
+  # Whether the method has a call-seq.
+
+  def has_call_seq?
+    !!(@call_seq || is_alias_for&._call_seq)
+  end
+
   ##
   # Loads is_alias_for from the internal name.  Returns nil if the alias
   # cannot be found.
@@ -181,7 +193,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @full_name     = array[2]
     @singleton     = array[3]
     @visibility    = array[4]
-    @comment       = array[5]
+    @comment       = RDoc::Comment.from_document array[5]
     @call_seq      = array[6]
     @block_params  = array[7]
     #                      8 handled below
@@ -193,8 +205,8 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @section_title = array[14]
     @is_alias_for  = array[15]
 
-    array[8].each do |new_name, comment|
-      add_alias RDoc::Alias.new(nil, @name, new_name, comment, @singleton)
+    array[8].each do |new_name, document|
+      add_alias RDoc::Alias.new(nil, @name, new_name, RDoc::Comment.from_document(document), singleton: @singleton)
     end
 
     @parent_name ||= if @full_name =~ /#/ then
@@ -244,9 +256,9 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     if @block_params then
       # If this method has explicit block parameters, remove any explicit
       # &block
-      params.sub!(/,?\s*&\w+/, '')
+      params = params.sub(/,?\s*&\w+/, '')
     else
-      params.sub!(/\&(\w+)/, '\1')
+      params = params.sub(/\&(\w+)/, '\1')
     end
 
     params = params.gsub(/\s+/, '').split(',').reject(&:empty?)
@@ -265,7 +277,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       params = params.sub(/(\|[^|]+\|)\s*\.\.\.\s*(end|\})/, '\1 \2')
     elsif @params then
       params = @params.gsub(/\s*\#.*/, '')
-      params = params.tr("\n", " ").squeeze(" ")
+      params = params.tr_s("\n ", " ")
       params = "(#{params})" unless params[0] == ?(
     else
       params = ''
@@ -274,12 +286,11 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     if @block_params then
       # If this method has explicit block parameters, remove any explicit
       # &block
-      params.sub!(/,?\s*&\w+/, '')
+      params = params.sub(/,?\s*&\w+/, '')
 
-      block = @block_params.gsub(/\s*\#.*/, '')
-      block = block.tr("\n", " ").squeeze(" ")
+      block = @block_params.tr_s("\n ", " ")
       if block[0] == ?(
-        block.sub!(/^\(/, '').sub!(/\)/, '')
+        block = block.sub(/^\(/, '').sub(/\)/, '')
       end
       params << " { |#{block}| ... }"
     end
@@ -287,6 +298,14 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     params
   end
 
+  ##
+  # Whether to skip the method description, true for methods that have
+  # aliases with a call-seq that doesn't include the method name.
+
+  def skip_description?
+    has_call_seq? && call_seq.nil? && !!(is_alias_for || !aliases.empty?)
+  end
+
   ##
   # Sets the store for this method and its referenced code objects.
 
@@ -313,5 +332,43 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @superclass_method
   end
 
-end
+  protected
+
+  ##
+  # call_seq without deduplication and alias lookup.
+
+  def _call_seq
+    @call_seq if defined?(@call_seq) && @call_seq
+  end
+
+  private
+
+  ##
+  # call_seq with alias examples information removed, if this
+  # method is an alias method.
+
+  def deduplicate_call_seq(call_seq)
+    return call_seq unless is_alias_for || !aliases.empty?
+
+    method_name = self.name
+    method_name = method_name[0, 1] if method_name =~ /\A\[/
+
+    entries = call_seq.split "\n"
+
+    ignore = aliases.map(&:name)
+    if is_alias_for
+      ignore << is_alias_for.name
+      ignore.concat is_alias_for.aliases.map(&:name)
+    end
+    ignore.map! { |n| n =~ /\A\[/ ? /\[.*\]/ : n}
+    ignore.delete(method_name)
+    ignore = Regexp.union(ignore)
+
+    matching = entries.reject do |entry|
+      entry =~ /^\w*\.?#{ignore}[$\(\s]/ or
+        entry =~ /\s#{ignore}\s/
+    end
 
+    matching.empty? ? nil : matching.join("\n")
+  end
+end

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

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # An attribute created by \#attr, \#attr_reader, \#attr_writer or
 # \#attr_accessor
@@ -22,11 +22,10 @@ class RDoc::Attr < RDoc::MethodAttr
   # Creates a new Attr with body +text+, +name+, read/write status +rw+ and
   # +comment+.  +singleton+ marks this as a class attribute.
 
-  def initialize(text, name, rw, comment, singleton = false)
-    super text, name
+  def initialize(text, name, rw, comment, singleton: false)
+    super(text, name, singleton: singleton)
 
     @rw = rw
-    @singleton = singleton
     self.comment = comment
   end
 
@@ -44,9 +43,7 @@ class RDoc::Attr < RDoc::MethodAttr
   # Add +an_alias+ as an attribute in +context+.
 
   def add_alias(an_alias, context)
-    new_attr = self.class.new(self.text, an_alias.new_name, self.rw,
-                              self.comment, self.singleton)
-
+    new_attr = self.class.new(text, an_alias.new_name, rw, comment, singleton: singleton)
     new_attr.record_location an_alias.file
     new_attr.visibility = self.visibility
     new_attr.is_alias_for = self
@@ -136,7 +133,7 @@ class RDoc::Attr < RDoc::MethodAttr
     @full_name     = array[2]
     @rw            = array[3]
     @visibility    = array[4]
-    @comment       = array[5]
+    @comment       = RDoc::Comment.from_document array[5]
     @singleton     = array[6] || false # MARSHAL_VERSION == 0
     #                      7 handled below
     @parent_name   = array[8]
@@ -173,4 +170,3 @@ class RDoc::Attr < RDoc::MethodAttr
   end
 
 end
-

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

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # ClassModule is the base class for objects representing either a class or a
 # module.
@@ -34,8 +34,6 @@ class RDoc::ClassModule < RDoc::Context
 
   attr_accessor :comment_location
 
-  attr_accessor :diagram # :nodoc:
-
   ##
   # Class or module this constant is an alias for
 
@@ -56,7 +54,6 @@ class RDoc::ClassModule < RDoc::Context
 
     klass.parent = mod.parent
     klass.section = mod.section
-    klass.viewer = mod.viewer
 
     klass.attributes.concat mod.attributes
     klass.method_list.concat mod.method_list
@@ -110,7 +107,6 @@ class RDoc::ClassModule < RDoc::Context
 
   def initialize(name, superclass = nil)
     @constant_aliases = []
-    @diagram          = nil
     @is_alias_for     = nil
     @name             = name
     @superclass       = superclass
@@ -136,7 +132,9 @@ class RDoc::ClassModule < RDoc::Context
                 normalize_comment comment
               end
 
-    @comment_location.delete_if { |(_, l)| l == location }
+    if location.parser == RDoc::Parser::C
+      @comment_location.delete_if { |(_, l)| l == location }
+    end
 
     @comment_location << [comment, location]
 
@@ -208,7 +206,7 @@ class RDoc::ClassModule < RDoc::Context
                 normalize_comment comment
               end
 
-    comment = "#{@comment}\n---\n#{comment}" unless @comment.empty?
+    comment = "#{@comment.to_s}\n---\n#{comment.to_s}" unless @comment.empty?
 
     super comment
   end
@@ -221,7 +219,9 @@ class RDoc::ClassModule < RDoc::Context
   def complete min_visibility
     update_aliases
     remove_nodoc_children
+    embed_mixins
     update_includes
+    update_extends
     remove_invisible min_visibility
   end
 
@@ -292,6 +292,25 @@ class RDoc::ClassModule < RDoc::Context
                    end
   end
 
+  ##
+  # Return array of full_name splitted by +::+.
+
+  def nesting_namespaces
+    @namespaces ||= full_name.split("::").reject(&:empty?)
+  end
+
+  ##
+  # Return array of fully qualified nesting namespaces.
+  #
+  # For example, if full_name is +A::B::C+, this method returns <code>["A", "A::B", "A::B::C"]</code>
+
+  def fully_qualified_nesting_namespaces
+    return nesting_namespaces if nesting_namespaces.length < 2
+    @fqns ||= nesting_namespaces.inject([]) do |list, n|
+      list << (list.empty? ? n : "#{list.last}::#{n}")
+    end
+  end
+
   ##
   # TODO: filter included items by #display?
 
@@ -356,37 +375,39 @@ class RDoc::ClassModule < RDoc::Context
     @name       = array[1]
     @full_name  = array[2]
     @superclass = array[3]
-    @comment    = array[4]
+    document    = array[4]
 
-    @comment_location = if RDoc::Markup::Document === @comment.parts.first then
-                          @comment
+    @comment    = RDoc::Comment.from_document document
+
+    @comment_location = if RDoc::Markup::Document === document.parts.first then
+                          document
                         else
-                          RDoc::Markup::Document.new @comment
+                          RDoc::Markup::Document.new document
                         end
 
     array[5].each do |name, rw, visibility, singleton, file|
       singleton  ||= false
       visibility ||= :public
 
-      attr = RDoc::Attr.new nil, name, rw, nil, singleton
+      attr = RDoc::Attr.new nil, name, rw, nil, singleton: singleton
 
       add_attribute attr
       attr.visibility = visibility
       attr.record_location RDoc::TopLevel.new file
     end
 
-    array[6].each do |constant, comment, file|
+    array[6].each do |constant, document, file|
       case constant
       when RDoc::Constant then
         add_constant constant
       else
-        constant = add_constant RDoc::Constant.new(constant, nil, comment)
+        constant = add_constant RDoc::Constant.new(constant, nil, RDoc::Comment.from_document(document))
         constant.record_location RDoc::TopLevel.new file
       end
     end
 
-    array[7].each do |name, comment, file|
-      incl = add_include RDoc::Include.new(name, comment)
+    array[7].each do |name, document, file|
+      incl = add_include RDoc::Include.new(name, RDoc::Comment.from_document(document))
       incl.record_location RDoc::TopLevel.new file
     end
 
@@ -395,16 +416,15 @@ class RDoc::ClassModule < RDoc::Context
         @visibility = visibility
 
         methods.each do |name, file|
-          method = RDoc::AnyMethod.new nil, name
-          method.singleton = true if type == 'class'
+          method = RDoc::AnyMethod.new nil, name, singleton: type == 'class'
           method.record_location RDoc::TopLevel.new file
           add_method method
         end
       end
     end
 
-    array[9].each do |name, comment, file|
-      ext = add_extend RDoc::Extend.new(name, comment)
+    array[9].each do |name, document, file|
+      ext = add_extend RDoc::Extend.new(name, RDoc::Comment.from_document(document))
       ext.record_location RDoc::TopLevel.new file
     end if array[9] # Support Marshal version 1
 
@@ -441,7 +461,8 @@ class RDoc::ClassModule < RDoc::Context
 
       document = document.merge other_document
 
-      @comment = @comment_location = document
+      @comment = RDoc::Comment.from_document(document)
+      @comment_location = document
     end
 
     cm = class_module
@@ -609,7 +630,9 @@ class RDoc::ClassModule < RDoc::Context
   # Path to this class or module for use with HTML generator output.
 
   def path
-    http_url @store.rdoc.generator.class_dir
+    prefix = options.class_module_path_prefix
+    return http_url unless prefix
+    File.join(prefix, http_url)
   end
 
   ##
@@ -702,10 +725,37 @@ class RDoc::ClassModule < RDoc::Context
 
   ##
   # Set the superclass of this class to +superclass+
+  #
+  # where +superclass+ is one of:
+  #
+  # - +nil+
+  # - a String containing the full name of the superclass
+  # - the RDoc::ClassModule representing the superclass
 
   def superclass=(superclass)
     raise NoMethodError, "#{full_name} is a module" if module?
-    @superclass = superclass
+    case superclass
+    when RDoc::ClassModule
+      @superclass = superclass.full_name
+    when nil, String
+      @superclass = superclass
+    else
+      raise TypeError, "superclass must be a String or RDoc::ClassModule, not #{superclass.class}"
+    end
+  end
+
+  ##
+  # Get all super classes of this class in an array. The last element might be
+  # a string if the name is unknown.
+
+  def super_classes
+    result = []
+    parent = self
+    while parent = parent.superclass
+      result << parent
+      return result if parent.is_a?(String)
+    end
+    result
   end
 
   def to_s # :nodoc:
@@ -796,5 +846,43 @@ class RDoc::ClassModule < RDoc::Context
     extends.uniq!
   end
 
-end
+  def embed_mixins
+    return unless options.embed_mixins
+
+    includes.each do |include|
+      next if String === include.module
+      include.module.method_list.each do |code_object|
+        add_method(prepare_to_embed(code_object))
+      end
+      include.module.constants.each do |code_object|
+        add_constant(prepare_to_embed(code_object))
+      end
+      include.module.attributes.each do |code_object|
+        add_attribute(prepare_to_embed(code_object))
+      end
+    end
 
+    extends.each do |ext|
+      next if String === ext.module
+      ext.module.method_list.each do |code_object|
+        add_method(prepare_to_embed(code_object, true))
+      end
+      ext.module.attributes.each do |code_object|
+        add_attribute(prepare_to_embed(code_object, true))
+      end
+    end
+  end
+
+  private
+
+  def prepare_to_embed(code_object, singleton=false)
+    code_object = code_object.dup
+    code_object.mixin_from = code_object.parent
+    code_object.singleton = true if singleton
+    set_current_section(code_object.section.title, code_object.section.comment)
+    # add_method and add_attribute will reassign self's visibility back to the method/attribute
+    # so we need to sync self's visibility with the object's to properly retain that information
+    self.visibility = code_object.visibility
+    code_object
+  end
+end

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

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 ##
 # A constant
 
@@ -36,7 +36,7 @@ class RDoc::Constant < RDoc::CodeObject
     @value = value
 
     @is_alias_for = nil
-    @visibility   = nil
+    @visibility   = :public
 
     self.comment = comment
   end
@@ -133,10 +133,10 @@ class RDoc::Constant < RDoc::CodeObject
   # * #parent_name
 
   def marshal_load array
-    initialize array[1], nil, array[5]
+    initialize array[1], nil, RDoc::Comment.from_document(array[5])
 
     @full_name     = array[2]
-    @visibility    = array[3]
+    @visibility    = array[3] || :public
     @is_alias_for  = array[4]
     #                      5 handled above
     #                      6 handled below
@@ -184,4 +184,3 @@ class RDoc::Constant < RDoc::CodeObject
   end
 
 end
-