diff --git a/lib/rdoc/code_object.rb b/lib/rdoc/code_object.rb
index 83997c2580..e4aedf3de4 100644
--- a/lib/rdoc/code_object.rb
+++ b/lib/rdoc/code_object.rb
@@ -141,7 +141,6 @@ def initialize_visibility # :nodoc:
   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
diff --git a/lib/rdoc/code_object/any_method.rb b/lib/rdoc/code_object/any_method.rb
index 465c4a4fb2..843e3cff90 100644
--- a/lib/rdoc/code_object/any_method.rb
+++ b/lib/rdoc/code_object/any_method.rb
@@ -198,7 +198,7 @@ def marshal_load array
     @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
@@ -210,8 +210,8 @@ def marshal_load array
     @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)
     end
 
     @parent_name ||= if @full_name =~ /#/ then
diff --git a/lib/rdoc/code_object/attr.rb b/lib/rdoc/code_object/attr.rb
index a403235933..b53b040a5e 100644
--- a/lib/rdoc/code_object/attr.rb
+++ b/lib/rdoc/code_object/attr.rb
@@ -136,7 +136,7 @@ def marshal_load array
     @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]
diff --git a/lib/rdoc/code_object/class_module.rb b/lib/rdoc/code_object/class_module.rb
index 33e71ab3f3..cfb298e0b7 100644
--- a/lib/rdoc/code_object/class_module.rb
+++ b/lib/rdoc/code_object/class_module.rb
@@ -359,12 +359,14 @@ def marshal_load array # :nodoc:
     @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|
@@ -378,18 +380,18 @@ def marshal_load array # :nodoc:
       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
 
@@ -406,8 +408,8 @@ def marshal_load array # :nodoc:
       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
 
@@ -444,7 +446,8 @@ def merge class_module
 
       document = document.merge other_document
 
-      @comment = @comment_location = document
+      @comment = RDoc::Comment.from_document(document)
+      @comment_location = document
     end
 
     cm = class_module
diff --git a/lib/rdoc/code_object/constant.rb b/lib/rdoc/code_object/constant.rb
index 12b8be775c..d524b7231a 100644
--- a/lib/rdoc/code_object/constant.rb
+++ b/lib/rdoc/code_object/constant.rb
@@ -133,7 +133,7 @@ def marshal_dump
   # * #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] || :public
diff --git a/lib/rdoc/code_object/context/section.rb b/lib/rdoc/code_object/context/section.rb
index aecd4e0213..4f39a1586e 100644
--- a/lib/rdoc/code_object/context/section.rb
+++ b/lib/rdoc/code_object/context/section.rb
@@ -61,19 +61,10 @@ def == other
   # Adds +comment+ to this section
 
   def add_comment comment
-    comment = extract_comment comment
-
-    return if comment.empty?
-
-    case comment
-    when RDoc::Comment then
-      @comments << comment
-    when RDoc::Markup::Document then
-      @comments.concat comment.parts
-    when Array then
-      @comments.concat comment
-    else
-      raise TypeError, "unknown comment type: #{comment.inspect}"
+    comments = Array(comment)
+    comments.each do |c|
+      extracted_comment = extract_comment(c)
+      @comments << extracted_comment unless extracted_comment.empty?
     end
   end
 
@@ -97,10 +88,6 @@ def aref
 
   def extract_comment comment
     case comment
-    when Array then
-      comment.map do |c|
-        extract_comment c
-      end
     when nil
       RDoc::Comment.new ''
     when RDoc::Comment then
@@ -115,8 +102,6 @@ def extract_comment comment
                        end
       end
 
-      comment
-    when RDoc::Markup::Document then
       comment
     else
       raise TypeError, "unknown comment #{comment.inspect}"
@@ -135,20 +120,7 @@ def hash # :nodoc:
   # The files comments in this section come from
 
   def in_files
-    return [] if @comments.empty?
-
-    case @comments
-    when Array then
-      @comments.map do |comment|
-        comment.file
-      end
-    when RDoc::Markup::Document then
-      @comment.parts.map do |document|
-        document.file
-      end
-    else
-      raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
-    end
+    @comments.map(&:file)
   end
 
   ##
@@ -170,7 +142,7 @@ def marshal_load array
     @parent  = nil
 
     @title    = array[1]
-    @comments = array[2]
+    @comments = array[2].parts.map { |doc| RDoc::Comment.from_document(doc) }
   end
 
   ##
@@ -178,26 +150,7 @@ def marshal_load array
   # multiple RDoc::Markup::Documents with their file set.
 
   def parse
-    case @comments
-    when String then
-      super
-    when Array then
-      docs = @comments.map do |comment, location|
-        doc = super comment
-        doc.file = location if location
-        doc
-      end
-
-      RDoc::Markup::Document.new(*docs)
-    when RDoc::Comment then
-      doc = super @comments.text, comments.format
-      doc.file = @comments.location
-      doc
-    when RDoc::Markup::Document then
-      return @comments
-    else
-      raise ArgumentError, "unknown comment class #{comments.class}"
-    end
+    RDoc::Markup::Document.new(*@comments.map(&:parse))
   end
 
   ##
@@ -213,20 +166,9 @@ def plain_html
   # Removes a comment from this section if it is from the same file as
   # +comment+
 
-  def remove_comment comment
-    return if @comments.empty?
-
-    case @comments
-    when Array then
-      @comments.delete_if do |my_comment|
-        my_comment.file == comment.file
-      end
-    when RDoc::Markup::Document then
-      @comments.parts.delete_if do |document|
-        document.file == comment.file.name
-      end
-    else
-      raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
+  def remove_comment target_comment
+    @comments.delete_if do |stored_comment|
+      stored_comment.file == target_comment.file
     end
   end
 
diff --git a/lib/rdoc/code_object/top_level.rb b/lib/rdoc/code_object/top_level.rb
index b93e3802fc..57091ba08b 100644
--- a/lib/rdoc/code_object/top_level.rb
+++ b/lib/rdoc/code_object/top_level.rb
@@ -214,7 +214,7 @@ def marshal_load array # :nodoc:
     initialize array[1]
 
     @parser  = array[2]
-    @comment = array[3]
+    @comment = RDoc::Comment.from_document array[3]
 
     @file_stat          = nil
   end
diff --git a/lib/rdoc/comment.rb b/lib/rdoc/comment.rb
index 04ec226436..464b3650f8 100644
--- a/lib/rdoc/comment.rb
+++ b/lib/rdoc/comment.rb
@@ -126,7 +126,7 @@ def extract_call_seq method
   # A comment is empty if its text String is empty.
 
   def empty?
-    @text.empty?
+    @text.empty? && (@document.nil? || @document.empty?)
   end
 
   ##
@@ -226,4 +226,14 @@ def tomdoc?
     @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
diff --git a/lib/rdoc/generator/darkfish.rb b/lib/rdoc/generator/darkfish.rb
index cfd46b5ed4..da266d737e 100644
--- a/lib/rdoc/generator/darkfish.rb
+++ b/lib/rdoc/generator/darkfish.rb
@@ -783,20 +783,13 @@ def template_for file, page = true, klass = ERB
     template
   end
 
-  # Returns an excerpt of the content for usage in meta description tags
-  def excerpt(content)
-    text = case content
+  # 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
diff --git a/lib/rdoc/parser/changelog.rb b/lib/rdoc/parser/changelog.rb
index 12a50f8d0e..7954792596 100644
--- a/lib/rdoc/parser/changelog.rb
+++ b/lib/rdoc/parser/changelog.rb
@@ -210,8 +210,9 @@ def scan
     grouped_entries = group_entries entries
 
     doc = create_document grouped_entries
-
-    @top_level.comment = doc
+    comment = RDoc::Comment.new(@content)
+    comment.document = doc
+    @top_level.comment = comment
 
     @top_level
   end
diff --git a/lib/rdoc/ri/driver.rb b/lib/rdoc/ri/driver.rb
index 18bfc941f1..959136af7a 100644
--- a/lib/rdoc/ri/driver.rb
+++ b/lib/rdoc/ri/driver.rb
@@ -518,7 +518,7 @@ def add_extension_modules_multiple out, store, modules # :nodoc:
     with.each do |incl|
       out << RDoc::Markup::Paragraph.new(incl.name)
       out << RDoc::Markup::BlankLine.new
-      out << incl.comment
+      out << incl.comment.parse
     end
 
     unless wout.empty? then
@@ -542,7 +542,7 @@ def add_extension_modules_single out, store, include # :nodoc:
 
     if include.comment then
       out << RDoc::Markup::BlankLine.new
-      out << include.comment
+      out << include.comment.parse
     end
   end
 
@@ -657,12 +657,12 @@ def class_document name, found, klasses, includes, extends
   ##
   # Adds the class +comment+ to +out+.
 
-  def class_document_comment out, comment # :nodoc:
-    unless comment.empty? then
+  def class_document_comment out, document # :nodoc:
+    unless document.empty? then
       out << RDoc::Markup::Rule.new(1)
 
-      if comment.merged? then
-        parts = comment.parts
+      if document.merged? then
+        parts = document.parts
         parts = parts.zip [RDoc::Markup::BlankLine.new] * parts.length
         parts.flatten!
         parts.pop
@@ -687,7 +687,7 @@ def class_document_constants out, klass # :nodoc:
     constants = klass.constants.sort_by { |constant| constant.name }
 
     list.items.concat constants.map { |constant|
-      parts = constant.comment.parts if constant.comment
+      parts = constant.comment.parse.parts
       parts << RDoc::Markup::Paragraph.new('[not documented]') if
         parts.empty?
 
@@ -906,7 +906,7 @@ def display_page name
 
     page = store.load_page page_name
 
-    display page.comment
+    display page.comment.parse
   end
 
   ##
@@ -1207,7 +1207,8 @@ def load_method store, cache, klass, type, name
 
     store.load_method klass, "#{type}#{method}"
   rescue RDoc::Store::MissingFileError => e
-    comment = RDoc::Comment.new("missing documentation at #{e.file}").parse
+    comment = RDoc::Comment.new("missing documentation at #{e.file}")
+    comment.parse
 
     method = RDoc::AnyMethod.new nil, name
     method.comment = comment
@@ -1367,13 +1368,13 @@ def parse_name name
   # documentable items the class is added to +also_in+ instead.
 
   def render_class out, store, klass, also_in # :nodoc:
-    comment = klass.comment
+    document = klass.comment.parse
     # TODO the store's cache should always return an empty Array
     class_methods    = store.class_methods[klass.full_name]    || []
     instance_methods = store.instance_methods[klass.full_name] || []
     attributes       = store.attributes[klass.full_name]       || []
 
-    if comment.empty? and
+    if document.empty? and
        instance_methods.empty? and class_methods.empty? then
       also_in << store
       return
@@ -1381,7 +1382,7 @@ def render_class out, store, klass, also_in # :nodoc:
 
     add_from out, store
 
-    class_document_comment out, comment
+    class_document_comment out, document
 
     if class_methods or instance_methods or not klass.constants.empty? then
       out << RDoc::Markup::Rule.new(1)
@@ -1429,16 +1430,16 @@ def render_method_comment out, method, alias_for = nil# :nodoc:
     if alias_for
       unless method.comment.nil? or method.comment.empty?
         out << RDoc::Markup::BlankLine.new
-        out << method.comment
+        out << method.comment.parse
       end
       out << RDoc::Markup::BlankLine.new
       out << RDoc::Markup::Paragraph.new("(This method is an alias for #{alias_for.full_name}.)")
       out << RDoc::Markup::BlankLine.new
-      out << alias_for.comment
+      out << alias_for.comment.parse
       out << RDoc::Markup::BlankLine.new
     else
       out << RDoc::Markup::BlankLine.new
-      out << method.comment
+      out << method.comment.parse
       out << RDoc::Markup::BlankLine.new
     end
   end
@@ -1551,7 +1552,7 @@ def expand_rdoc_refs_at_the_bottom(out)
     found_pages.each do |page|
       out << RDoc::Markup::Heading.new(4, "Expanded from #{page.full_name}")
       out << RDoc::Markup::BlankLine.new
-      out << page.comment
+      out << page.comment.parse
     end
   end
 end
diff --git a/test/rdoc/test_rdoc_any_method.rb b/test/rdoc/test_rdoc_any_method.rb
index b11c15420c..4ea554a129 100644
--- a/test/rdoc/test_rdoc_any_method.rb
+++ b/test/rdoc/test_rdoc_any_method.rb
@@ -223,15 +223,15 @@ def test_marshal_dump
     loaded = Marshal.load Marshal.dump m
     loaded.store = @store
 
-    comment = RDoc::Markup::Document.new(
-                RDoc::Markup::Paragraph.new('this is a comment'))
+    document = RDoc::Markup::Document.new(
+                 RDoc::Markup::Paragraph.new('this is a comment'))
 
     assert_equal m, loaded
 
     assert_equal [al_m.name],    loaded.aliases.map { |alas| alas.name }
     assert_equal 'some_block',   loaded.block_params
     assert_equal 'call_seq',     loaded.call_seq
-    assert_equal comment,        loaded.comment
+    assert_equal document,       loaded.comment.parse
     assert_equal top_level,      loaded.file
     assert_equal 'Klass#method', loaded.full_name
     assert_equal 'method',       loaded.name
@@ -311,15 +311,15 @@ def test_marshal_load_version_0
 
     loaded.store = @store
 
-    comment = RDoc::Markup::Document.new(
-                RDoc::Markup::Paragraph.new('this is a comment'))
+    document = RDoc::Markup::Document.new(
+                 RDoc::Markup::Paragraph.new('this is a comment'))
 
     assert_equal m, loaded
 
     assert_equal [al_m.name],    loaded.aliases.map { |alas| alas.name }
     assert_equal 'some_block',   loaded.block_params
     assert_equal 'call_seq',     loaded.call_seq
-    assert_equal comment,        loaded.comment
+    assert_equal document,       loaded.comment.parse
     assert_equal 'Klass#method', loaded.full_name
     assert_equal 'method',       loaded.name
     assert_equal 'param',        loaded.params
@@ -368,14 +368,14 @@ def test_marshal_dump_version_2
 
     loaded.store = @store
 
-    comment = doc(para('this is a comment'))
+    document = doc(para('this is a comment'))
 
     assert_equal m, loaded
 
     assert_equal [al_m.name],    loaded.aliases.map { |alas| alas.name }
     assert_equal 'some_block',   loaded.block_params
     assert_equal 'call_seq',     loaded.call_seq
-    assert_equal comment,        loaded.comment
+    assert_equal document,       loaded.comment.parse
     assert_equal top_level,      loaded.file
     assert_equal 'Klass#method', loaded.full_name
     assert_equal 'method',       loaded.name
diff --git a/test/rdoc/test_rdoc_attr.rb b/test/rdoc/test_rdoc_attr.rb
index cff52acf31..98c6e6af4b 100644
--- a/test/rdoc/test_rdoc_attr.rb
+++ b/test/rdoc/test_rdoc_attr.rb
@@ -59,10 +59,10 @@ def test_marshal_dump
 
     assert_equal @a, loaded
 
-    comment = RDoc::Markup::Document.new(
-                RDoc::Markup::Paragraph.new('this is a comment'))
+    document = RDoc::Markup::Document.new(
+                 RDoc::Markup::Paragraph.new('this is a comment'))
 
-    assert_equal comment,      loaded.comment
+    assert_equal document,      loaded.comment.parse
     assert_equal 'file.rb',    loaded.file.relative_name
     assert_equal 'Klass#attr', loaded.full_name
     assert_equal 'attr',       loaded.name
@@ -94,10 +94,10 @@ def test_marshal_dump_singleton
 
     assert_equal @a, loaded
 
-    comment = RDoc::Markup::Document.new(
-                RDoc::Markup::Paragraph.new('this is a comment'))
+    document = RDoc::Markup::Document.new(
+                 RDoc::Markup::Paragraph.new('this is a comment'))
 
-    assert_equal comment,       loaded.comment
+    assert_equal document,      loaded.comment.parse
     assert_equal 'Klass::attr', loaded.full_name
     assert_equal 'attr',        loaded.name
     assert_equal 'R',           loaded.rw
@@ -122,10 +122,10 @@ def test_marshal_load_version_1
     loaded = Marshal.load data
     loaded.store = @store
 
-    comment = RDoc::Markup::Document.new(
-                RDoc::Markup::Paragraph.new('this is a comment'))
+    document = RDoc::Markup::Document.new(
+                 RDoc::Markup::Paragraph.new('this is a comment'))
 
-    assert_equal comment,      loaded.comment
+    assert_equal document,     loaded.comment.parse
     assert_equal 'Klass#attr', loaded.full_name
     assert_equal 'attr',       loaded.name
     assert_equal 'RW',         loaded.rw
@@ -155,9 +155,9 @@ def test_marshal_load_version_2
                           "@file0FI\"\ffile.rb\x06;\x06T"
     loaded.store = @store
 
-    comment = doc(para('this is a comment'))
+    document = doc(para('this is a comment'))
 
-    assert_equal comment,      loaded.comment
+    assert_equal document,     loaded.comment.parse
     assert_equal 'Klass#attr', loaded.full_name
     assert_equal 'attr',       loaded.name
     assert_equal 'RW',         loaded.rw
diff --git a/test/rdoc/test_rdoc_class_module.rb b/test/rdoc/test_rdoc_class_module.rb
index ded5bc8d09..0752949398 100644
--- a/test/rdoc/test_rdoc_class_module.rb
+++ b/test/rdoc/test_rdoc_class_module.rb
@@ -210,10 +210,10 @@ def test_marshal_dump
       RDoc::Markup::Paragraph.new('this is a comment'))
     inner.file = tl
 
-    comment = RDoc::Markup::Document.new inner
+    document = RDoc::Markup::Document.new(inner)
 
     assert_equal [a2, a1],           loaded.attributes.sort
-    assert_equal comment,            loaded.comment
+    assert_equal document,           loaded.comment.parse
     assert_equal [c1],               loaded.constants
     assert_equal 'Namespace::Klass', loaded.full_name
     assert_equal [i1],               loaded.includes
@@ -326,11 +326,11 @@ def test_marshal_load_version_0
 
     assert_equal cm, loaded
 
-    comment = RDoc::Markup::Document.new(
-                RDoc::Markup::Paragraph.new('this is a comment'))
+    document = RDoc::Markup::Document.new(
+                 RDoc::Markup::Paragraph.new('this is a comment'))
 
     assert_equal [a],                loaded.attributes
-    assert_equal comment,            loaded.comment
+    assert_equal document,           loaded.comment.parse
     assert_equal [c],                loaded.constants
     assert_equal 'Namespace::Klass', loaded.full_name
     assert_equal [i],                loaded.includes
@@ -403,10 +403,10 @@ def test_marshal_load_version_1
       RDoc::Markup::Paragraph.new('this is a comment'))
     inner.file = tl
 
-    comment = RDoc::Markup::Document.new inner
+    document = RDoc::Markup::Document.new(inner)
 
     assert_equal [a2, a1],           loaded.attributes.sort
-    assert_equal comment,            loaded.comment
+    assert_equal document,           loaded.comment.parse
     assert_equal [c1],               loaded.constants
     assert_equal 'Namespace::Klass', loaded.full_name
     assert_equal [i1],               loaded.includes
@@ -487,10 +487,10 @@ def test_marshal_load_version_2
       RDoc::Markup::Paragraph.new('this is a comment'))
     inner.file = tl
 
-    comment = RDoc::Markup::Document.new inner
+    document = RDoc::Markup::Document.new(inner)
 
     assert_equal [a2, a1],           loaded.attributes.sort
-    assert_equal comment,            loaded.comment
+    assert_equal document,           loaded.comment.parse
     assert_equal [c1],               loaded.constants
     assert_equal 'Namespace::Klass', loaded.full_name
     assert_equal [i1],               loaded.includes
@@ -585,10 +585,10 @@ def test_marshal_load_version_3
       RDoc::Markup::Paragraph.new('this is a comment'))
     inner.file = tl
 
-    comment = RDoc::Markup::Document.new inner
+    document = RDoc::Markup::Document.new(inner)
 
     assert_equal [a2, a1],           loaded.attributes.sort
-    assert_equal comment,            loaded.comment
+    assert_equal document,           loaded.comment.parse
     assert_equal [c1],               loaded.constants
     assert_equal 'Namespace::Klass', loaded.full_name
     assert_equal [i1],               loaded.includes
@@ -752,7 +752,7 @@ def test_merge_comment
 
     expected = @RM::Document.new inner2, inner1
 
-    assert_equal expected, cm1.comment
+    assert_equal expected, cm1.comment.parse
   end
 
   def test_merge_comment_version_0
@@ -777,7 +777,7 @@ def test_merge_comment_version_0
       inner,
       @RM::Document.new(@RM::Paragraph.new('klass 2'))
 
-    assert_equal expected, cm1.comment
+    assert_equal expected, cm1.comment.parse
   end
 
   def test_merge_constants
diff --git a/test/rdoc/test_rdoc_code_object.rb b/test/rdoc/test_rdoc_code_object.rb
index 24e228cce1..8cf278f0ea 100644
--- a/test/rdoc/test_rdoc_code_object.rb
+++ b/test/rdoc/test_rdoc_code_object.rb
@@ -40,13 +40,12 @@ def test_comment_equals_comment
     assert_equal 'I am a comment', @co.comment.text
   end
 
-  def test_comment_equals_document
-    doc = RDoc::Markup::Document.new
-    @co.comment = doc
+  def test_comment_equals_empty_string
+    @co.comment = 'comment'
 
     @co.comment = ''
 
-    assert_equal doc, @co.comment
+    assert_equal 'comment', @co.comment
   end
 
   def test_comment_equals_encoding
diff --git a/test/rdoc/test_rdoc_comment.rb b/test/rdoc/test_rdoc_comment.rb
index 28e8cf76b4..c36e0fdf5e 100644
--- a/test/rdoc/test_rdoc_comment.rb
+++ b/test/rdoc/test_rdoc_comment.rb
@@ -14,12 +14,17 @@ def setup
     @comment.text = 'this is a comment'
   end
 
-  def test_empty_eh
-    refute_empty @comment
-
-    @comment = ''
-
+  def test_empty
+    @comment.text = ''
     assert_empty @comment
+    empty_doc = @comment.parse
+    assert_empty @comment
+    @comment.text = 'a'
+    refute_empty @comment
+    present_doc = @comment.parse
+    refute_empty @comment
+    assert_empty RDoc::Comment.from_document(empty_doc)
+    refute_empty RDoc::Comment.from_document(present_doc)
   end
 
   def test_equals2
diff --git a/test/rdoc/test_rdoc_constant.rb b/test/rdoc/test_rdoc_constant.rb
index 32ffe3f84d..f1930fbc62 100644
--- a/test/rdoc/test_rdoc_constant.rb
+++ b/test/rdoc/test_rdoc_constant.rb
@@ -77,12 +77,12 @@ def test_marshal_dump
     loaded = Marshal.load Marshal.dump c
     loaded.store = @store
 
-    comment = doc(para('this is a comment'))
+    document = doc(para('this is a comment'))
 
     assert_equal c, loaded
 
     assert_equal aliased,        loaded.is_alias_for
-    assert_equal comment,        loaded.comment
+    assert_equal document,       loaded.comment.parse
     assert_equal top_level,      loaded.file
     assert_equal 'Klass::CONST', loaded.full_name
     assert_equal 'CONST',        loaded.name
@@ -105,12 +105,12 @@ def test_marshal_load
     loaded = Marshal.load Marshal.dump c
     loaded.store = @store
 
-    comment = doc(para('this is a comment'))
+    document = doc(para('this is a comment'))
 
     assert_equal c, loaded
 
     assert_nil                   loaded.is_alias_for
-    assert_equal comment,        loaded.comment
+    assert_equal document,       loaded.comment.parse
     assert_equal top_level,      loaded.file
     assert_equal 'Klass::CONST', loaded.full_name
     assert_equal 'CONST',        loaded.name
@@ -139,10 +139,10 @@ def test_marshal_load_version_0
 
     loaded.store = @store
 
-    comment = doc(para('this is a comment'))
+    document = doc(para('this is a comment'))
 
     assert_equal aliased,        loaded.is_alias_for
-    assert_equal comment,        loaded.comment
+    assert_equal document,       loaded.comment.parse
     assert_equal top_level,      loaded.file
     assert_equal 'Klass::CONST', loaded.full_name
     assert_equal 'CONST',        loaded.name
diff --git a/test/rdoc/test_rdoc_context_section.rb b/test/rdoc/test_rdoc_context_section.rb
index 6834cccafb..76f2a832ed 100644
--- a/test/rdoc/test_rdoc_context_section.rb
+++ b/test/rdoc/test_rdoc_context_section.rb
@@ -83,11 +83,10 @@ def test_hash
   def test_marshal_dump
     loaded = Marshal.load Marshal.dump @s
 
-    expected = RDoc::Comment.new('comment', @top_level).parse
-    expected = doc(expected)
+    expected = doc RDoc::Comment.new('comment', @top_level).parse
 
     assert_equal 'section', loaded.title
-    assert_equal expected,  loaded.comments
+    assert_equal expected,  loaded.parse
     assert_nil              loaded.parent, 'parent is set manually'
   end
 
@@ -113,7 +112,7 @@ def test_marshal_load_version_0
     expected = doc RDoc::Comment.new('comment', @top_level).parse
 
     assert_equal 'section', loaded.title
-    assert_equal expected,  loaded.comments
+    assert_equal expected,  loaded.parse
     assert_nil              loaded.parent, 'parent is set manually'
   end
 
@@ -140,7 +139,7 @@ def test_remove_comment_document
 
     loaded.remove_comment comment('bogus', @top_level)
 
-    assert_equal doc(other_comment.parse), loaded.comments
+    assert_equal doc(other_comment.parse), loaded.parse
   end
 
 end
diff --git a/test/rdoc/test_rdoc_generator_darkfish.rb b/test/rdoc/test_rdoc_generator_darkfish.rb
index cedc876b4e..ed84543ee1 100644
--- a/test/rdoc/test_rdoc_generator_darkfish.rb
+++ b/test/rdoc/test_rdoc_generator_darkfish.rb
@@ -469,21 +469,20 @@ def test_meta_tags_for_markdown_files
 
   def test_meta_tags_for_raw_pages
     top_level = @store.add_file("MyPage", parser: RDoc::Parser::Simple)
-    top_level.comment = RDoc::Markup::Document.new(RDoc::Markup::Paragraph.new('this is a comment'))
+    comment = RDoc::Comment.new('this is a comment')
+    comment.document = RDoc::Markup::Document.new(RDoc::Markup::Paragraph.new('this is a comment'))
+    top_level.comment = comment
 
     @g.generate
 
     content = File.binread("MyPage.html")
     assert_include(content, '<meta name="keywords" content="ruby,documentation,MyPage">')
-    assert_include(
-      content,
-      '<meta name="description" content="MyPage: this is a comment ">',
-    )
+    assert_include(content, '<meta name="description" content="MyPage: this is a comment">')
   end
 
   def test_meta_tags_for_empty_document
     top_level = @store.add_file("MyPage", parser: RDoc::Parser::Simple)
-    top_level.comment = RDoc::Markup::Document.new
+    top_level.comment = RDoc::Comment.from_document(RDoc::Markup::Document.new)
 
     @g.generate
 
diff --git a/test/rdoc/test_rdoc_parser_changelog.rb b/test/rdoc/test_rdoc_parser_changelog.rb
index c61c5cf825..36275eca17 100644
--- a/test/rdoc/test_rdoc_parser_changelog.rb
+++ b/test/rdoc/test_rdoc_parser_changelog.rb
@@ -326,7 +326,7 @@ def test_scan
 
     expected.file = @top_level
 
-    assert_equal expected, @top_level.comment
+    assert_equal expected, @top_level.comment.parse
   end
 
   def test_scan_git
@@ -430,7 +430,7 @@ def test_scan_git
 
     expected.file = @top_level
 
-    assert_equal expected, @top_level.comment
+    assert_equal expected, @top_level.comment.parse
   end
 
   def test_scan_git_commit_date
@@ -470,7 +470,7 @@ def test_scan_git_commit_date
 
     expected.file = @top_level
 
-    assert_equal expected, @top_level.comment
+    assert_equal expected, @top_level.comment.parse
   end
 
   def util_parser content = ''
diff --git a/test/rdoc/test_rdoc_ri_driver.rb b/test/rdoc/test_rdoc_ri_driver.rb
index 37372391cf..74b7f013a8 100644
--- a/test/rdoc/test_rdoc_ri_driver.rb
+++ b/test/rdoc/test_rdoc_ri_driver.rb
@@ -860,9 +860,9 @@ def test_display_page_ambiguous
     other = @store1.add_file 'README.md'
     other.parser = RDoc::Parser::Simple
     other.comment =
-      doc(
+      RDoc::Comment.from_document(doc(
         head(1, 'README.md'),
-        para('This is the other README'))
+        para('This is the other README')))
 
     @store1.save_page other
 
@@ -881,9 +881,9 @@ def test_display_page_extension
     other = @store1.add_file 'README.EXT'
     other.parser = RDoc::Parser::Simple
     other.comment =
-      doc(
+      RDoc::Comment.from_document(doc(
         head(1, 'README.EXT'),
-        para('This is the other README'))
+        para('This is the other README')))
 
     @store1.save_page other
 
@@ -900,9 +900,9 @@ def test_display_page_ignore_directory
     other = @store1.add_file 'doc/globals.rdoc'
     other.parser = RDoc::Parser::Simple
     other.comment =
-      doc(
+      RDoc::Comment.from_document(doc(
         head(1, 'globals.rdoc'),
-        para('Globals go here'))
+        para('Globals go here')))
 
     @store1.save_page other
 
@@ -934,9 +934,9 @@ def test_display_page_list
     other = @store1.add_file 'OTHER.rdoc'
     other.parser = RDoc::Parser::Simple
     other.comment =
-      doc(
+      RDoc::Comment.from_document(doc(
         head(1, 'OTHER'),
-        para('This is OTHER'))
+        para('This is OTHER')))
 
     @store1.save_page other
 
@@ -1543,10 +1543,7 @@ def util_store
 
     @readme = @store1.add_file 'README.rdoc'
     @readme.parser = RDoc::Parser::Simple
-    @readme.comment =
-      doc(
-        head(1, 'README'),
-        para('This is a README'))
+    @readme.comment = RDoc::Comment.from_document(doc(head(1, 'README'), para('This is a README')))
 
     @cFoo = @top_level.add_class RDoc::NormalClass, 'Foo'
     @mExt = @top_level.add_module RDoc::NormalModule, 'Ext'
@@ -1554,10 +1551,10 @@ def util_store
     @cAmbiguous = @top_level.add_class RDoc::NormalClass, 'Ambiguous'
 
     doc = @RM::Document.new @RM::Paragraph.new('Extend thingy')
-    @cFooExt = @cFoo.add_extend RDoc::Extend.new('Ext', doc)
+    @cFooExt = @cFoo.add_extend RDoc::Extend.new('Ext', RDoc::Comment.from_document(doc))
     @cFooExt.record_location @top_level
     doc = @RM::Document.new @RM::Paragraph.new('Include thingy')
-    @cFooInc = @cFoo.add_include RDoc::Include.new('Inc', doc)
+    @cFooInc = @cFoo.add_include RDoc::Include.new('Inc', RDoc::Comment.from_document(doc))
     @cFooInc.record_location @top_level
 
     @cFoo_Bar = @cFoo.add_class RDoc::NormalClass, 'Bar'
diff --git a/test/rdoc/test_rdoc_store.rb b/test/rdoc/test_rdoc_store.rb
index 6631d04db9..13485cd075 100644
--- a/test/rdoc/test_rdoc_store.rb
+++ b/test/rdoc/test_rdoc_store.rb
@@ -404,7 +404,7 @@ def test_load_all
                  methods.sort_by { |m| m.full_name }
 
     method = methods.find { |m| m == @meth }
-    assert_equal @meth_comment.parse, method.comment
+    assert_equal @meth_comment.parse, method.comment.parse
 
     assert_equal @klass, methods.last.parent
 
@@ -414,7 +414,7 @@ def test_load_all
 
     assert_equal [@attr], attributes
 
-    assert_equal @attr_comment.parse, attributes.first.comment
+    assert_equal @attr_comment.parse, attributes.first.comment.parse
   end
 
   def test_load_cache
diff --git a/test/rdoc/test_rdoc_top_level.rb b/test/rdoc/test_rdoc_top_level.rb
index 3cfaa9b763..a9f2b232e9 100644
--- a/test/rdoc/test_rdoc_top_level.rb
+++ b/test/rdoc/test_rdoc_top_level.rb
@@ -177,9 +177,9 @@ def test_marshal_dump
 
     loaded = Marshal.load Marshal.dump page
 
-    comment = RDoc::Markup::Document.new(
-                RDoc::Markup::Paragraph.new('This is a page'))
-    comment.file = loaded
+    document = RDoc::Markup::Document.new(
+                 RDoc::Markup::Paragraph.new('This is a page'))
+    document.file = loaded
 
     assert_equal page, loaded
 
@@ -188,7 +188,7 @@ def test_marshal_dump
 
     assert_equal RDoc::Parser::Simple, loaded.parser
 
-    assert_equal comment, loaded.comment
+    assert_equal document, loaded.comment.parse
   end
 
   def test_marshal_load_version_0
@@ -199,16 +199,16 @@ def test_marshal_load_version_0
                           "[\x06o:\x1CRDoc::Markup::Paragraph\x06;\b" +
                           "[\x06I\"\x13This is a page\x06;\x06F:\n@file@\a"
 
-    comment = RDoc::Markup::Document.new(
-                RDoc::Markup::Paragraph.new('This is a page'))
-    comment.file = loaded
+    document = RDoc::Markup::Document.new(
+                 RDoc::Markup::Paragraph.new('This is a page'))
+    document.file = loaded
 
     assert_equal 'README.txt', loaded.absolute_name
     assert_equal 'README.txt', loaded.relative_name
 
     assert_equal RDoc::Parser::Simple, loaded.parser
 
-    assert_equal comment, loaded.comment
+    assert_equal document, loaded.comment.parse
 
     assert loaded.display?
   end