rdoc 3.6.1 → 3.7

data/lib/rdoc/ruby_lex.rb

@@ -407,7 +407,7 @@ class RDoc::RubyLex
         (ch = getc)
         res << ch
       end
-  
+
       gets # consume =end
 
       @ltype = nil

data/lib/rdoc/rubygems_hook.rb

@@ -0,0 +1,220 @@
+require 'rubygems'
+require 'rubygems/user_interaction'
+require 'fileutils'
+require 'rdoc'
+
+##
+# Gem::RDoc provides methods to generate RDoc and ri data for installed gems
+# upon gem installation.
+#
+# This file is automatically required by RubyGems 1.9 and newer.
+
+class RDoc::RubygemsHook
+
+  include Gem::UserInteraction
+
+  @rdoc_version = nil
+  @specs = []
+
+  ##
+  # Force installation of documentation?
+
+  attr_accessor :force
+
+  ##
+  # Generate rdoc?
+
+  attr_accessor :generate_rdoc
+
+  ##
+  # Generate ri data?
+
+  attr_accessor :generate_ri
+
+  class << self
+
+    ##
+    # Loaded version of RDoc.  Set by ::load_rdoc
+
+    attr_reader :rdoc_version
+
+  end
+
+  ##
+  # Post installs hook that generates documentation for each specification in
+  # +specs+
+
+  def self.generation_hook installer, specs
+    types     = installer.document
+
+    generate_rdoc = types.include? 'rdoc'
+    generate_ri   = types.include? 'ri'
+
+    specs.each do |spec|
+      new(spec, generate_rdoc, generate_ri).generate
+    end
+  end
+
+  ##
+  # Loads the RDoc generator
+
+  def self.load_rdoc
+    return if @rdoc_version
+
+    require 'rdoc/rdoc'
+
+    @rdoc_version = Gem::Version.new ::RDoc::VERSION
+  end
+
+  ##
+  # Creates a new documentation generator for +spec+.  RDoc and ri data
+  # generation can be disabled through +generate_rdoc+ and +generate_ri+
+  # respectively.
+
+  def initialize spec, generate_rdoc = true, generate_ri = true
+    @doc_dir   = spec.doc_dir
+    @file_info = nil
+    @force     = false
+    @rdoc      = nil
+    @spec      = spec
+
+    @generate_rdoc = generate_rdoc
+    @generate_ri   = generate_ri
+
+    @rdoc_dir = spec.doc_dir 'rdoc'
+    @ri_dir   = spec.doc_dir 'ri'
+  end
+
+  ##
+  # Removes legacy rdoc arguments from +args+
+  #--
+  # TODO move to RDoc::Options
+
+  def delete_legacy_args args
+    args.delete '--inline-source'
+    args.delete '--promiscuous'
+    args.delete '-p'
+    args.delete '--one-file'
+  end
+
+  ##
+  # Generates documentation using the named +generator+ ("darkfish" or "ri")
+  # and following the given +options+.
+  #
+  # Documentation will be generated into +destination+
+
+  def document generator, options, destination
+    options = options.dup
+    options.exclude ||= [] # TODO maybe move to RDoc::Options#finish
+    options.setup_generator generator
+    options.op_dir = destination
+    options.finish
+
+    @rdoc.options = options
+    @rdoc.generator = options.generator.new options
+
+    say "Installing #{generator} documentation for #{@spec.full_name}"
+
+    FileUtils.mkdir_p options.op_dir
+
+    Dir.chdir options.op_dir do
+      begin
+        @rdoc.class.current = @rdoc
+        @rdoc.generator.generate @file_info
+      ensure
+        @rdoc.class.current = nil
+      end
+    end
+  end
+
+  ##
+  # Generates RDoc and ri data
+
+  def generate
+    return unless @generate_ri or @generate_rdoc
+
+    setup
+
+    ::RDoc::RDoc.reset
+
+    options = ::RDoc::Options.new
+    options.default_title = "#{@spec.full_name} Documentation"
+    options.files = []
+    options.files.push(*@spec.require_paths)
+    options.files.push(*@spec.extra_rdoc_files)
+
+    args = @spec.rdoc_options
+
+    case config_args = Gem.configuration[:rdoc]
+    when String then
+      args = args.concat config_args.split
+    when Array then
+      args = args.concat config_args
+    end
+
+    delete_legacy_args args
+    options.parse args
+    options.quiet = !Gem.configuration.really_verbose
+
+    @rdoc = new_rdoc
+    @rdoc.options = options
+
+    Dir.chdir @spec.full_gem_path do
+      @file_info = @rdoc.parse_files options.files
+    end
+
+    document 'ri',       options, @ri_dir if
+      @generate_ri   and (@force or not File.exist? @ri_dir)
+
+    document 'darkfish', options, @rdoc_dir if
+      @generate_rdoc and (@force or not File.exist? @rdoc_dir)
+  end
+
+  ##
+  # #new_rdoc creates a new RDoc instance.  This method is provided only to
+  # make testing easier.
+
+  def new_rdoc # :nodoc:
+    ::RDoc::RDoc.new
+  end
+
+  ##
+  # Is rdoc documentation installed?
+
+  def rdoc_installed?
+    File.exist? @rdoc_dir
+  end
+
+  ##
+  # Removes generated RDoc and ri data
+
+  def remove
+    base_dir = @spec.base_dir
+
+    raise Gem::FilePermissionError, base_dir unless File.writable? base_dir
+
+    FileUtils.rm_rf @rdoc_dir
+    FileUtils.rm_rf @ri_dir
+  end
+
+  ##
+  # Is ri data installed?
+
+  def ri_installed?
+    File.exist? @ri_dir
+  end
+
+  ##
+  # Prepares the spec for documentation generation
+
+  def setup
+    self.class.load_rdoc
+
+    raise Gem::FilePermissionError, @doc_dir if
+      File.exist?(@doc_dir) and not File.writable?(@doc_dir)
+
+    FileUtils.mkdir_p @doc_dir unless File.exist? @doc_dir
+  end
+
+end
+

data/lib/rdoc/text.rb

@@ -157,7 +157,7 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
   def strip_stars text
     encoding = text.encoding if Object.const_defined? :Encoding
 
-    text = text.gsub %r%Document-method:\s+[\w:.#]+%, ''
+    text = text.gsub %r%Document-method:\s+[\w:.#=!?]+%, ''
 
     space = ' '
     space.force_encoding encoding if encoding

data/lib/rdoc/top_level.rb

@@ -219,6 +219,20 @@ class RDoc::TopLevel < RDoc::Context
     end
   end
 
+  ##
+  # Creates a new RDoc::TopLevel with +file_name+ only if one with the same
+  # name does not exist in all_files.
+
+  def self.new file_name
+    if top_level = @all_files_hash[file_name] then
+      top_level
+    else
+      top_level = super
+      @all_files_hash[file_name] = top_level
+      top_level
+    end
+  end
+
   ##
   # Removes from +all_hash+ the contexts that are nodoc or have no content.
   #
@@ -295,6 +309,15 @@ class RDoc::TopLevel < RDoc::Context
     RDoc::TopLevel.files_hash[file_name] = self
   end
 
+  ##
+  # An RDoc::TopLevel is equal to another with the same absolute_name
+
+  def == other
+    other.class === self and @absolute_name == other.absolute_name
+  end
+
+  alias eql? ==
+
   ##
   # Adds +an_alias+ to +Object+ instead of +self+.
 
@@ -375,6 +398,14 @@ class RDoc::TopLevel < RDoc::Context
     @relative_name
   end
 
+  ##
+  # An RDoc::TopLevel has the same hash as another with the same
+  # absolute_name
+
+  def hash
+    @absolute_name.hash
+  end
+
   ##
   # URL for this with a +prefix+
 

data/test/test_rdoc_any_method.rb

@@ -83,6 +83,40 @@ method(a, b) { |c, d| ... }
     assert_equal '', @c2_a.markup_code
   end
 
+  def test_marshal_dump
+    top_level = RDoc::TopLevel.new 'file.rb'
+    m = RDoc::AnyMethod.new nil, 'method'
+    m.block_params = 'some_block'
+    m.call_seq     = 'call_seq'
+    m.comment      = 'this is a comment'
+    m.params       = 'param'
+    m.record_location top_level
+
+    cm = RDoc::ClassModule.new 'Klass'
+    cm.add_method m
+
+    al = RDoc::Alias.new nil, 'method', 'aliased', 'alias comment'
+    al_m = m.add_alias al, cm
+
+    loaded = Marshal.load Marshal.dump m
+
+    comment = RDoc::Markup::Document.new(
+                RDoc::Markup::Paragraph.new('this is a comment'))
+
+    assert_equal m, loaded
+
+    assert_equal [al_m],         loaded.aliases
+    assert_equal 'some_block',   loaded.block_params
+    assert_equal 'call_seq',     loaded.call_seq
+    assert_equal comment,        loaded.comment
+    assert_equal top_level,      loaded.file
+    assert_equal 'Klass#method', loaded.full_name
+    assert_equal 'method',       loaded.name
+    assert_equal 'param',        loaded.params
+    assert_equal nil,            loaded.singleton # defaults to nil
+    assert_equal :public,        loaded.visibility
+  end
+
   def test_marshal_load
     instance_method = Marshal.load Marshal.dump(@c1.method_list.last)
 
@@ -103,6 +137,40 @@ method(a, b) { |c, d| ... }
     assert_equal '()',    class_method.params
   end
 
+  def test_marshal_load_version_0
+    m = RDoc::AnyMethod.new nil, 'method'
+    cm = RDoc::ClassModule.new 'Klass'
+    cm.add_method m
+    al = RDoc::Alias.new nil, 'method', 'aliased', 'alias comment'
+    al_m = m.add_alias al, cm
+
+    loaded = Marshal.load "\x04\bU:\x14RDoc::AnyMethod[\x0Fi\x00I" \
+                          "\"\vmethod\x06:\x06EF\"\x11Klass#method0:\vpublic" \
+                          "o:\eRDoc::Markup::Document\x06:\v@parts[\x06" \
+                          "o:\x1CRDoc::Markup::Paragraph\x06;\t[\x06I" \
+                          "\"\x16this is a comment\x06;\x06FI" \
+                          "\"\rcall_seq\x06;\x06FI\"\x0Fsome_block\x06;\x06F" \
+                          "[\x06[\aI\"\faliased\x06;\x06Fo;\b\x06;\t[\x06" \
+                          "o;\n\x06;\t[\x06I\"\x12alias comment\x06;\x06FI" \
+                          "\"\nparam\x06;\x06F"
+
+    comment = RDoc::Markup::Document.new(
+                RDoc::Markup::Paragraph.new('this is a comment'))
+
+    assert_equal m, loaded
+
+    assert_equal [al_m],         loaded.aliases
+    assert_equal 'some_block',   loaded.block_params
+    assert_equal 'call_seq',     loaded.call_seq
+    assert_equal comment,        loaded.comment
+    assert_equal 'Klass#method', loaded.full_name
+    assert_equal 'method',       loaded.name
+    assert_equal 'param',        loaded.params
+    assert_equal nil,            loaded.singleton # defaults to nil
+    assert_equal :public,        loaded.visibility
+    assert_equal nil,            loaded.file
+  end
+
   def test_name
     m = RDoc::AnyMethod.new nil, nil
 

data/test/test_rdoc_attr.rb

@@ -42,6 +42,68 @@ class TestRDocAttr < MiniTest::Unit::TestCase
     assert_equal '(unknown)#attr', @a.full_name
   end
 
+  def test_marshal_dump
+    tl = RDoc::TopLevel.new 'file.rb'
+
+    @a.comment = 'this is a comment'
+    @a.record_location tl
+
+    cm = RDoc::ClassModule.new 'Klass'
+    cm.add_attribute @a
+
+    loaded = Marshal.load Marshal.dump @a
+
+    assert_equal @a, loaded
+
+    comment = RDoc::Markup::Document.new(
+                RDoc::Markup::Paragraph.new('this is a comment'))
+
+    assert_equal comment,      loaded.comment
+    assert_equal 'file.rb',    loaded.file.relative_name
+    assert_equal 'Klass#attr', loaded.full_name
+    assert_equal 'attr',       loaded.name
+    assert_equal 'RW',         loaded.rw
+    assert_equal false,        loaded.singleton
+    assert_equal :public,      loaded.visibility
+
+    @a.rw = 'R'
+    @a.singleton = true
+    @a.visibility = :protected
+
+    loaded = Marshal.load Marshal.dump @a
+
+    assert_equal @a, loaded
+
+    assert_equal comment,       loaded.comment
+    assert_equal 'Klass::attr', loaded.full_name
+    assert_equal 'attr',        loaded.name
+    assert_equal 'R',           loaded.rw
+    assert_equal true,          loaded.singleton
+    assert_equal :protected,    loaded.visibility
+  end
+
+  def test_marshal_load_version_1
+    data = "\x04\bU:\x0FRDoc::Attr[\fi\x06I\"\tattr\x06:\x06EF" \
+           "\"\x0FKlass#attrI\"\aRW\x06;\x06F:\vpublic" \
+           "o:\eRDoc::Markup::Document\x06:\v@parts[\x06" \
+           "o:\x1CRDoc::Markup::Paragraph\x06;\t[\x06I" \
+           "\"\x16this is a comment\x06;\x06FF"
+
+    loaded = Marshal.load data
+
+    comment = RDoc::Markup::Document.new(
+                RDoc::Markup::Paragraph.new('this is a comment'))
+
+    assert_equal comment,      loaded.comment
+    assert_equal 'Klass#attr', loaded.full_name
+    assert_equal 'attr',       loaded.name
+    assert_equal 'RW',         loaded.rw
+    assert_equal false,        loaded.singleton
+    assert_equal :public,      loaded.visibility
+
+    assert_equal nil,          loaded.file # version 2
+  end
+
   def test_params
     assert_nil @a.params
   end

data/test/test_rdoc_class_module.rb

@@ -1,3 +1,4 @@
+require 'pp'
 require File.expand_path '../xref_test_case', __FILE__
 
 class TestRDocClassModule < XrefTestCase
@@ -8,6 +9,37 @@ class TestRDocClassModule < XrefTestCase
     @RM = RDoc::Markup
   end
 
+  def mu_pp obj
+    s = ''
+    s = PP.pp obj, s
+    s.force_encoding Encoding.default_external if defined? Encoding
+    s.chomp
+  end
+
+  def test_add_comment
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+    tl3 = RDoc::TopLevel.new 'three.rb'
+
+    cm = RDoc::ClassModule.new 'Klass'
+    cm.add_comment '# comment 1', tl1
+
+    assert_equal [['comment 1', tl1]], cm.comment_location
+    assert_equal 'comment 1', cm.comment
+
+    cm.add_comment '# comment 2', tl2
+
+    assert_equal [['comment 1', tl1], ['comment 2', tl2]], cm.comment_location
+    assert_equal "comment 1\n---\ncomment 2", cm.comment
+
+    cm.add_comment "# * comment 3", tl3
+
+    assert_equal [['comment 1', tl1],
+                  ['comment 2', tl2],
+                  ['* comment 3', tl3]], cm.comment_location
+    assert_equal "comment 1\n---\ncomment 2\n---\n* comment 3", cm.comment
+  end
+
   def test_ancestors
     assert_equal [@parent], @child.ancestors
   end
@@ -45,70 +77,468 @@ class TestRDocClassModule < XrefTestCase
     assert_nil @c2.find_class_named('C1')
   end
 
-  def test_merge
+  def test_from_module_comment
+    tl = RDoc::TopLevel.new 'file.rb'
+    klass = tl.add_class RDoc::NormalModule, 'Klass'
+    klass.add_comment 'really a class', tl
+
+    klass = RDoc::ClassModule.from_module RDoc::NormalClass, klass
+
+    assert_equal [['really a class', tl]], klass.comment_location
+  end
+
+  def test_marshal_dump
+    tl = RDoc::TopLevel.new 'file.rb'
+
+    ns = tl.add_module RDoc::NormalModule, 'Namespace'
+
+    cm = ns.add_class RDoc::NormalClass, 'Klass', 'Super'
+    cm.record_location tl
+
+    a1 = RDoc::Attr.new nil, 'a1', 'RW', ''
+    a1.record_location tl
+    a2 = RDoc::Attr.new nil, 'a2', 'RW', '', true
+    a2.record_location tl
+
+    m1 = RDoc::AnyMethod.new nil, 'm1'
+    m1.record_location tl
+
+    c1 = RDoc::Constant.new 'C1', nil, ''
+    c1.record_location tl
+
+    i1 = RDoc::Include.new 'I1', ''
+    i1.record_location tl
+
+    cm.add_attribute a1
+    cm.add_attribute a2
+    cm.add_method m1
+    cm.add_constant c1
+    cm.add_include i1
+    cm.add_comment 'this is a comment', tl
+
+    loaded = Marshal.load Marshal.dump cm
+
+    assert_equal cm, loaded
+
+    inner = RDoc::Markup::Document.new(
+      RDoc::Markup::Paragraph.new('this is a comment'))
+    inner.file = tl.absolute_name
+
+    comment = RDoc::Markup::Document.new inner
+
+    assert_equal [a2, a1],           loaded.attributes.sort
+    assert_equal comment,            loaded.comment
+    assert_equal [c1],               loaded.constants
+    assert_equal 'Namespace::Klass', loaded.full_name
+    assert_equal [i1],               loaded.includes
+    assert_equal [m1],               loaded.method_list
+    assert_equal 'Klass',            loaded.name
+    assert_equal 'Super',            loaded.superclass
+
+    assert_equal tl, loaded.attributes.first.file
+
+    assert_equal tl, loaded.constants.first.file
+
+    assert_equal tl, loaded.includes.first.file
+
+    assert_equal tl, loaded.method_list.first.file
+  end
+
+  def test_marshal_load_version_0
+    tl = RDoc::TopLevel.new 'file.rb'
+    ns = tl.add_module RDoc::NormalModule, 'Namespace'
+    cm = ns.add_class RDoc::NormalClass, 'Klass', 'Super'
+
+    a = RDoc::Attr.new(nil, 'a1', 'RW', '')
+    m = RDoc::AnyMethod.new(nil, 'm1')
+    c = RDoc::Constant.new('C1', nil, '')
+    i = RDoc::Include.new('I1', '')
+
+    cm.add_attribute a
+    cm.add_method m
+    cm.add_constant c
+    cm.add_include i
+    cm.add_comment 'this is a comment', tl
+
+    loaded = Marshal.load "\x04\bU:\x16RDoc::NormalClass[\x0Ei\x00\"\nKlass" \
+                          "\"\x15Namespace::KlassI\"\nSuper\x06:\x06EF" \
+                          "o:\eRDoc::Markup::Document\x06:\v@parts[\x06" \
+                          "o:\x1CRDoc::Markup::Paragraph\x06;\b[\x06I" \
+                          "\"\x16this is a comment\x06;\x06F[\x06[\aI" \
+                          "\"\aa1\x06;\x06FI\"\aRW\x06;\x06F[\x06[\aI" \
+                          "\"\aC1\x06;\x06Fo;\a\x06;\b[\x00[\x06[\aI" \
+                          "\"\aI1\x06;\x06Fo;\a\x06;\b[\x00[\a[\aI" \
+                          "\"\nclass\x06;\x06F[\b[\a:\vpublic[\x00[\a" \
+                          ":\x0Eprotected[\x00[\a:\fprivate[\x00[\aI" \
+                          "\"\rinstance\x06;\x06F[\b[\a;\n[\x06I" \
+                          "\"\am1\x06;\x06F[\a;\v[\x00[\a;\f[\x00"
+
+    assert_equal cm, loaded
+
+    comment = RDoc::Markup::Document.new(
+                RDoc::Markup::Paragraph.new('this is a comment'))
+
+    assert_equal [a],                loaded.attributes
+    assert_equal comment,            loaded.comment
+    assert_equal [c],                loaded.constants
+    assert_equal 'Namespace::Klass', loaded.full_name
+    assert_equal [i],                loaded.includes
+    assert_equal [m],                loaded.method_list
+    assert_equal 'Klass',            loaded.name
+    assert_equal 'Super',            loaded.superclass
+    assert_equal nil,                loaded.file
+  end
+
+  def test_merge_attributes
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
     cm1 = RDoc::ClassModule.new 'Klass'
-    cm1.comment = 'klass 1'
-    cm1.add_attribute RDoc::Attr.new(nil, 'a1', 'RW', '')
-    cm1.add_attribute RDoc::Attr.new(nil, 'a3', 'R', '')
-    cm1.add_attribute RDoc::Attr.new(nil, 'a4', 'R', '')
-    cm1.add_constant RDoc::Constant.new('C1', nil, '')
-    cm1.add_include RDoc::Include.new('I1', '')
-    cm1.add_method RDoc::AnyMethod.new(nil, 'm1')
+
+    attr = cm1.add_attribute RDoc::Attr.new(nil, 'a1', 'RW', '')
+    attr.record_location tl1
+    attr = cm1.add_attribute RDoc::Attr.new(nil, 'a3', 'R', '')
+    attr.record_location tl1
+    attr = cm1.add_attribute RDoc::Attr.new(nil, 'a4', 'R', '')
+    attr.record_location tl1
 
     cm2 = RDoc::ClassModule.new 'Klass'
-    cm2.instance_variable_set(:@comment,
-                              @RM::Document.new(
-                                @RM::Paragraph.new('klass 2')))
-    cm2.add_attribute RDoc::Attr.new(nil, 'a2', 'RW', '')
-    cm2.add_attribute RDoc::Attr.new(nil, 'a3', 'W', '')
-    cm2.add_attribute RDoc::Attr.new(nil, 'a4', 'R', '')
-    cm2.add_constant RDoc::Constant.new('C2', nil, '')
-    cm2.add_include RDoc::Include.new('I2', '')
-    cm2.add_method RDoc::AnyMethod.new(nil, 'm2')
+    # TODO allow merging when comment == ''
+    cm2.instance_variable_set :@comment, @RM::Document.new
+
+    attr = cm2.add_attribute RDoc::Attr.new(nil, 'a2', 'RW', '')
+    attr.record_location tl2
+    attr = cm2.add_attribute RDoc::Attr.new(nil, 'a3', 'W', '')
+    attr.record_location tl1
+    attr = cm2.add_attribute RDoc::Attr.new(nil, 'a4', 'W', '')
+    attr.record_location tl1
 
     cm1.merge cm2
 
-    document = @RM::Document.new(
-      @RM::Paragraph.new('klass 2'),
-      @RM::Paragraph.new('klass 1'))
+    expected = [
+      RDoc::Attr.new(nil, 'a2', 'RW', ''),
+      RDoc::Attr.new(nil, 'a3', 'W',  ''),
+      RDoc::Attr.new(nil, 'a4', 'W',  ''),
+    ]
+
+    expected.each do |a| a.parent = cm1 end
+    assert_equal expected, cm1.attributes.sort
+  end
+
+  def test_merge_attributes_version_0
+    tl1 = RDoc::TopLevel.new 'one.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+
+    attr = cm1.add_attribute RDoc::Attr.new(nil, 'a1', 'RW', '')
+    attr.record_location tl1
+    attr = cm1.add_attribute RDoc::Attr.new(nil, 'a3', 'R', '')
+    attr.record_location tl1
+    attr = cm1.add_attribute RDoc::Attr.new(nil, 'a4', 'R', '')
+    attr.record_location tl1
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+    # TODO allow merging when comment == ''
+    cm2.instance_variable_set :@comment, @RM::Document.new
+
+    attr = cm2.add_attribute RDoc::Attr.new(nil, 'a2', 'RW', '')
+    attr = cm2.add_attribute RDoc::Attr.new(nil, 'a3', 'W', '')
+    attr = cm2.add_attribute RDoc::Attr.new(nil, 'a4', 'W', '')
 
-    assert_equal document, cm1.comment
+    cm1.merge cm2
 
     expected = [
       RDoc::Attr.new(nil, 'a1', 'RW', ''),
       RDoc::Attr.new(nil, 'a2', 'RW', ''),
       RDoc::Attr.new(nil, 'a3', 'RW', ''),
-      RDoc::Attr.new(nil, 'a4', 'R',  ''),
+      RDoc::Attr.new(nil, 'a4', 'RW', ''),
     ]
 
     expected.each do |a| a.parent = cm1 end
     assert_equal expected, cm1.attributes.sort
+  end
+
+  def test_merge_comment
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+    cm1.add_comment 'klass 1', tl1
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+    cm2.add_comment 'klass 2', tl2
+    cm2.add_comment 'klass 3', tl1
+
+    cm2 = Marshal.load Marshal.dump cm2
+
+    cm1.merge cm2
+
+    inner1 = @RM::Document.new @RM::Paragraph.new 'klass 3'
+    inner1.file = 'one.rb'
+    inner2 = @RM::Document.new @RM::Paragraph.new 'klass 2'
+    inner2.file = 'two.rb'
+
+    expected = @RM::Document.new inner2, inner1
+
+    assert_equal expected, cm1.comment
+  end
+
+  def test_merge_comment_version_0
+    tl = RDoc::TopLevel.new 'file.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+    cm1.add_comment 'klass 1', tl
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+
+    cm2.instance_variable_set(:@comment,
+                              @RM::Document.new(
+                                @RM::Paragraph.new('klass 2')))
+    cm2.instance_variable_set :@comment_location, @RM::Document.new(cm2.comment)
+
+    cm1.merge cm2
+
+    inner = @RM::Document.new @RM::Paragraph.new 'klass 1'
+    inner.file = 'file.rb'
+
+    expected = @RM::Document.new \
+      inner,
+      @RM::Document.new(@RM::Paragraph.new('klass 2'))
+
+    assert_equal expected, cm1.comment
+  end
+
+  def test_merge_constants
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+
+    const = cm1.add_constant RDoc::Constant.new('C1', nil, 'one')
+    const.record_location tl1
+    const = cm1.add_constant RDoc::Constant.new('C3', nil, 'one')
+    const.record_location tl1
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+    cm2.instance_variable_set :@comment, @RM::Document.new
+
+    const = cm2.add_constant RDoc::Constant.new('C2', nil, 'two')
+    const.record_location tl2
+    const = cm2.add_constant RDoc::Constant.new('C3', nil, 'one')
+    const.record_location tl1
+    const = cm2.add_constant RDoc::Constant.new('C4', nil, 'one')
+    const.record_location tl1
+
+    cm1.merge cm2
+
+    expected = [
+      RDoc::Constant.new('C2', nil, 'two'),
+      RDoc::Constant.new('C3', nil, 'one'),
+      RDoc::Constant.new('C4', nil, 'one'),
+    ]
+
+    expected.each do |a| a.parent = cm1 end
+
+    assert_equal expected, cm1.constants.sort
+  end
+
+  def test_merge_constants_version_0
+    tl1 = RDoc::TopLevel.new 'one.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+
+    const = cm1.add_constant RDoc::Constant.new('C1', nil, 'one')
+    const.record_location tl1
+    const = cm1.add_constant RDoc::Constant.new('C3', nil, 'one')
+    const.record_location tl1
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+    cm2.instance_variable_set :@comment, @RM::Document.new
+
+    const = cm2.add_constant RDoc::Constant.new('C2', nil, 'two')
+    const = cm2.add_constant RDoc::Constant.new('C3', nil, 'two')
+    const = cm2.add_constant RDoc::Constant.new('C4', nil, 'two')
+
+    cm1.merge cm2
 
     expected = [
-      RDoc::Constant.new('C1', nil, ''),
-      RDoc::Constant.new('C2', nil, ''),
+      RDoc::Constant.new('C1', nil, 'one'),
+      RDoc::Constant.new('C2', nil, 'two'),
+      RDoc::Constant.new('C3', nil, 'one'),
+      RDoc::Constant.new('C4', nil, 'two'),
     ]
 
-    expected.each do |c| c.parent = cm1 end
+    expected.each do |a| a.parent = cm1 end
+
     assert_equal expected, cm1.constants.sort
+  end
+
+  def test_merge_includes
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+
+    incl = cm1.add_include RDoc::Include.new('I1', 'one')
+    incl.record_location tl1
+    incl = cm1.add_include RDoc::Include.new('I3', 'one')
+    incl.record_location tl1
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+    cm2.instance_variable_set :@comment, @RM::Document.new
+
+    incl = cm2.add_include RDoc::Include.new('I2', 'two')
+    incl.record_location tl2
+    incl = cm2.add_include RDoc::Include.new('I3', 'one')
+    incl.record_location tl1
+    incl = cm2.add_include RDoc::Include.new('I4', 'one')
+    incl.record_location tl1
+
+    cm1.merge cm2
+
+    expected = [
+      RDoc::Include.new('I2', 'two'),
+      RDoc::Include.new('I3', 'one'),
+      RDoc::Include.new('I4', 'one'),
+    ]
+
+    expected.each do |a| a.parent = cm1 end
+
+    assert_equal expected, cm1.includes.sort
+  end
+
+  def test_merge_includes_version_0
+    tl1 = RDoc::TopLevel.new 'one.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+
+    incl = cm1.add_include RDoc::Include.new('I1', 'one')
+    incl.record_location tl1
+    incl = cm1.add_include RDoc::Include.new('I3', 'one')
+    incl.record_location tl1
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+    cm2.instance_variable_set :@comment, @RM::Document.new
+
+    incl = cm2.add_include RDoc::Include.new('I2', 'two')
+    incl = cm2.add_include RDoc::Include.new('I3', 'two')
+    incl = cm2.add_include RDoc::Include.new('I4', 'two')
+
+    cm1.merge cm2
 
     expected = [
-      RDoc::Include.new('I1', ''),
-      RDoc::Include.new('I2', ''),
+      RDoc::Include.new('I1', 'one'),
+      RDoc::Include.new('I2', 'two'),
+      RDoc::Include.new('I3', 'one'),
+      RDoc::Include.new('I4', 'two'),
     ]
 
-    expected.each do |i| i.parent = cm1 end
+    expected.each do |a| a.parent = cm1 end
+
     assert_equal expected, cm1.includes.sort
+  end
+
+  def test_merge_methods
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+
+    meth = cm1.add_method RDoc::AnyMethod.new(nil, 'm1')
+    meth.record_location tl1
+    meth = cm1.add_method RDoc::AnyMethod.new(nil, 'm3')
+    meth.record_location tl1
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+    cm2.instance_variable_set :@comment, @RM::Document.new
+
+    meth = cm2.add_method RDoc::AnyMethod.new(nil, 'm2')
+    meth.record_location tl2
+    meth = cm2.add_method RDoc::AnyMethod.new(nil, 'm3')
+    meth.record_location tl1
+    meth = cm2.add_method RDoc::AnyMethod.new(nil, 'm4')
+    meth.record_location tl1
+
+    cm1.merge cm2
+
+    expected = [
+      RDoc::AnyMethod.new(nil, 'm2'),
+      RDoc::AnyMethod.new(nil, 'm3'),
+      RDoc::AnyMethod.new(nil, 'm4'),
+    ]
+
+    expected.each do |a| a.parent = cm1 end
+
+    assert_equal expected, cm1.method_list.sort
+  end
+
+  def test_merge_methods_version_0
+    tl1 = RDoc::TopLevel.new 'one.rb'
+
+    cm1 = RDoc::ClassModule.new 'Klass'
+
+    meth = cm1.add_method RDoc::AnyMethod.new(nil, 'm1')
+    meth.record_location tl1
+    meth = cm1.add_method RDoc::AnyMethod.new(nil, 'm3')
+    meth.record_location tl1
+
+    cm2 = RDoc::ClassModule.new 'Klass'
+    cm2.instance_variable_set :@comment, @RM::Document.new
+
+    meth = cm2.add_method RDoc::AnyMethod.new(nil, 'm2')
+    meth = cm2.add_method RDoc::AnyMethod.new(nil, 'm3')
+    meth = cm2.add_method RDoc::AnyMethod.new(nil, 'm4')
+
+    cm1.merge cm2
 
     expected = [
       RDoc::AnyMethod.new(nil, 'm1'),
       RDoc::AnyMethod.new(nil, 'm2'),
+      RDoc::AnyMethod.new(nil, 'm3'),
+      RDoc::AnyMethod.new(nil, 'm4'),
     ]
 
-    expected.each do |m| m.parent = cm1 end
+    expected.each do |a| a.parent = cm1 end
+
     assert_equal expected, cm1.method_list.sort
   end
 
+  def test_parse
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
+    cm = RDoc::ClassModule.new 'Klass'
+    cm.add_comment 'comment 1', tl1
+    cm.add_comment 'comment 2', tl2
+
+    doc1 = @RM::Document.new @RM::Paragraph.new 'comment 1'
+    doc1.file = tl1.absolute_name
+    doc2 = @RM::Document.new @RM::Paragraph.new 'comment 2'
+    doc2.file = tl2.absolute_name
+
+    expected = @RM::Document.new doc1, doc2
+
+    assert_equal expected, cm.parse(cm.comment_location)
+  end
+
+  def test_parse_comment_location
+    tl1 = RDoc::TopLevel.new 'one.rb'
+    tl2 = RDoc::TopLevel.new 'two.rb'
+
+    cm = RDoc::ClassModule.new 'Klass'
+    cm.add_comment 'comment 1', tl1
+    cm.add_comment 'comment 2', tl2
+
+    cm = Marshal.load Marshal.dump cm
+
+    doc1 = @RM::Document.new @RM::Paragraph.new 'comment 1'
+    doc1.file = tl1.absolute_name
+    doc2 = @RM::Document.new @RM::Paragraph.new 'comment 2'
+    doc2.file = tl2.absolute_name
+
+    assert_same cm.comment_location, cm.parse(cm.comment_location)
+  end
+
   def test_remove_nodoc_children
     parent = RDoc::ClassModule.new 'A'
     parent.modules_hash.replace 'B' => true, 'C' => true