diff --git a/lib/rdoc/code_object/class_module.rb b/lib/rdoc/code_object/class_module.rb
index 76ded527a1..0a5647b51f 100644
--- a/lib/rdoc/code_object/class_module.rb
+++ b/lib/rdoc/code_object/class_module.rb
@@ -39,7 +39,7 @@ class RDoc::ClassModule < RDoc::Context
   #
   # Before marshalling:
   # - +location+ is an RDoc::TopLevel
-  # - +comments+ are Strings
+  # - +comments+ are Strings or RDoc::Comment objects
   #
   # After unmarshalling:
   # - +location+ is a filename String
@@ -364,7 +364,7 @@ def marshal_dump # :nodoc:
       @name,
       full_name,
       @superclass,
-      parse(@comment_location),
+      parse_comment_locations(@comment_location),
       attrs,
       constants.select { |constant| constant.display? },
       includes.map do |incl|
@@ -479,10 +479,15 @@ def merge(class_module)
     @parent      = class_module.parent
     @parent_name = class_module.parent_name
 
-    other_document = parse class_module.comment_location
+    other_comment_location = class_module.comment_location
+    other_document = if Hash === other_comment_location
+                       class_module.parse_comment_locations(other_comment_location)
+                     else
+                       parse(other_comment_location)
+                     end
 
     if other_document then
-      document = parse @comment_location
+      document = parse_comment_locations(@comment_location)
 
       document = document.merge other_document
 
@@ -630,32 +635,19 @@ def name=(new_name)
   end
 
   ##
-  # Parses +comment_location+ into an RDoc::Markup::Document composed of
+  # Parses +comment_locations+ into an RDoc::Markup::Document composed of
   # multiple RDoc::Markup::Documents with their file set.
 
-  def parse(comment_location)
-    case comment_location
-    when String then
-      super
-    when Hash then
-      docs = comment_location.flat_map do |location, comments|
-        comments.map do |comment|
-          doc = super comment
-          doc.file = location
-          doc
-        end
+  def parse_comment_locations(comment_locations)
+    docs = comment_locations.flat_map do |location, comments|
+      comments.map do |comment|
+        document = parse(comment)
+        document.file = location unless RDoc::Comment === comment
+        document
       end
-
-      RDoc::Markup::Document.new(*docs)
-    when RDoc::Comment then
-      doc = super comment_location.text, comment_location.format
-      doc.file = comment_location.location
-      doc
-    when RDoc::Markup::Document then
-      return comment_location
-    else
-      raise ArgumentError, "unknown comment class #{comment_location.class}"
     end
+
+    RDoc::Markup::Document.new(*docs)
   end
 
   ##
@@ -733,7 +725,7 @@ def search_record
       '',
       path,
       '',
-      snippet(@comment_location),
+      snippet(parse_comment_locations(@comment_location)),
     ]
   end
 
@@ -756,7 +748,7 @@ def rebuild_comment_from_location
       comments.filter_map { |c| c.to_s unless c.empty? }
     }
     merged = texts.join("\n---\n")
-    @comment = merged.empty? ? '' : RDoc::Comment.new(merged)
+    @comment = merged
   end
 
   ##
diff --git a/lib/rdoc/comment.rb b/lib/rdoc/comment.rb
index b50193d56c..abe9919856 100644
--- a/lib/rdoc/comment.rb
+++ b/lib/rdoc/comment.rb
@@ -19,9 +19,11 @@ class RDoc::Comment
   attr_reader :format
 
   ##
-  # The RDoc::TopLevel this comment was found in
+  # The source this comment was read from.  This is usually an
+  # RDoc::TopLevel.  A comment loaded from a generated document without a file
+  # uses that RDoc::Markup::Document as its source.
 
-  attr_accessor :location
+  attr_reader :markup_source
 
   ##
   # Line where this Comment was written
@@ -29,38 +31,28 @@ class RDoc::Comment
   attr_accessor :line
 
   ##
-  # For duck-typing when merging classes at load time
-
-  alias file location # :nodoc:
-
-  ##
-  # The text for this comment
+  # The text for this comment.
 
   attr_reader :text
 
   ##
-  # Alias for text
+  # Alias for text.
 
   alias to_s text
 
   ##
-  # Overrides the content returned by #parse.  Use when there is no #text
-  # source for this comment
+  # Creates a new comment with +text+ from +markup_source+.
 
-  attr_writer   :document
+  def initialize(text = nil, markup_source:, language: nil, format: 'rdoc', normalized: false)
+    raise ArgumentError, 'markup_source is required' unless markup_source
 
-  ##
-  # Creates a new comment with +text+ that is found in the RDoc::TopLevel
-  # +location+.
-
-  def initialize(text = nil, location = nil, language = nil)
-    @location = location
-    @text     = text.nil? ? nil : text.dup
-    @language = language
+    @markup_source = markup_source
+    @text         = text.nil? ? nil : text.dup
+    @language     = language
 
     @document   = nil
-    @format     = 'rdoc'
-    @normalized = false
+    @format     = format
+    @normalized = normalized
   end
 
   ##
@@ -68,19 +60,19 @@ def initialize(text = nil, location = nil, language = nil)
   # TODO deep copy @document
 
   def initialize_copy(copy) # :nodoc:
-    @text = copy.text.dup
+    @text = copy.text&.dup
   end
 
   def ==(other) # :nodoc:
     self.class === other and
-      other.text == @text and other.location == @location
+      other.text == @text and other.location == location
   end
 
   ##
   # A comment is empty if its text String is empty.
 
   def empty?
-    @text.empty? && (@document.nil? || @document.empty?)
+    @text.to_s.empty? && (@document.nil? || @document.empty?)
   end
 
   ##
@@ -92,17 +84,42 @@ def encode!(encoding)
   end
 
   ##
-  # Sets the format of this comment and resets any parsed document
+  # Sets the format of this comment and resets its parsed document.
 
   def format=(format)
     @format = format
     @document = nil
   end
 
+  ##
+  # Sets the language of this comment and resets its parsed document.
+
+  def language=(language)
+    @language = language
+    @document = nil
+  end
+
+  ##
+  # The RDoc::TopLevel this comment was found in.
+
+  def location
+    return @markup_source if RDoc::TopLevel === @markup_source
+    return @location if defined?(@location)
+
+    file = @markup_source.file if @markup_source.respond_to?(:file)
+    @location = RDoc::TopLevel.new(file) if file
+  end
+
+  ##
+  # For duck-typing when merging classes at load time.
+
+  alias file location # :nodoc:
+
   def inspect # :nodoc:
-    location = @location ? @location.relative_name : '(unknown)'
+    location = self.location
+    relative_name = location ? location.relative_name : '(unknown)'
 
-    "#<%s:%x %s %p>" % [self.class, object_id, location, @text]
+    "#<%s:%x %s %p>" % [self.class, object_id, relative_name, @text]
   end
 
   ##
@@ -112,7 +129,9 @@ def normalize
     return self unless @text
     return self if @normalized # TODO eliminate duplicate normalization
 
-    @text = normalize_comment @text
+    text = normalize_comment @text
+    @document = nil if text != @text
+    @text = text
 
     @normalized = true
 
@@ -134,13 +153,13 @@ def normalized? # :nodoc:
 
   ##
   # Parses the comment into an RDoc::Markup::Document.  The parsed document is
-  # cached until the text is changed.
+  # cached until the text, format, or language changes.
 
   def parse
     return @document if @document
 
     @document = super @text, @format
-    @document.file = @location
+    @document.file = location if location
     @document
   end
 
@@ -154,6 +173,7 @@ def text=(text)
       @text.nil? and @document
 
     @document = nil
+    @normalized = false
     @text = text.nil? ? nil : text.dup
   end
 
@@ -176,12 +196,24 @@ def tomdoc?
   class << self
 
     ##
-    # Create a new parsed comment from a document
-
-    def from_document(document) # :nodoc:
-      comment = RDoc::Comment.new('')
-      comment.document = document
-      comment.location = RDoc::TopLevel.new(document.file) if document.file
+    # Creates a comment from an already parsed +document+.
+
+    def from_document(document, text: '', markup_source: nil, language: nil, format: 'rdoc', normalized: false) # :nodoc:
+      markup_source ||= if document.file
+                          RDoc::TopLevel.new document.file
+                        else
+                          document
+                        end
+
+      comment = new(
+        text,
+        markup_source: markup_source,
+        language: language,
+        format: format,
+        normalized: normalized
+      )
+      comment.normalize
+      comment.instance_variable_set :@document, document
       comment
     end
 
diff --git a/lib/rdoc/generator/markup.rb b/lib/rdoc/generator/markup.rb
index d6a56adf97..fd10190328 100644
--- a/lib/rdoc/generator/markup.rb
+++ b/lib/rdoc/generator/markup.rb
@@ -166,7 +166,9 @@ class RDoc::ClassModule
   # Handy wrapper for marking up this class or module's comment
 
   def description
-    markup @comment_location
+    return markup(@comment_location) if @store.options&.locale
+
+    parse_comment_locations(@comment_location).accept(formatter)
   end
 
 end
diff --git a/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml b/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml
index a08a1eb3a2..1828c94e04 100644
--- a/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml
+++ b/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml
@@ -1,9 +1,14 @@
 <%- comment = if current.respond_to? :comment_location
-               current.comment_location
-             else
-               current.comment
-             end
-   table = current.parse(comment).table_of_contents.dup
+                current.comment_location
+              else
+                current.comment
+              end
+   document = if Hash === comment
+                current.parse_comment_locations(comment)
+               else
+                 current.parse(comment)
+               end
+   table = document.table_of_contents.dup
 
    if table.length > 1 %>
 <div class="nav-section">
diff --git a/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml b/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml
index b5bac664f1..29f0fa3a1e 100644
--- a/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml
+++ b/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml
@@ -41,7 +41,7 @@
   <li class="<%= klass.type %>">
     <a href="<%= klass.path %>"><%= klass.full_name %></a>
 <%- table = []
-   table.concat klass.parse(klass.comment_location).table_of_contents
+   table.concat klass.parse_comment_locations(klass.comment_location).table_of_contents
    table.concat klass.section_contents
 
    unless table.empty? %>
diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb
index 6adfd32ab8..08fa2df7ad 100644
--- a/lib/rdoc/parser/c.rb
+++ b/lib/rdoc/parser/c.rb
@@ -1219,8 +1219,11 @@ def scan
   # Creates a RDoc::Comment instance.
 
   def new_comment(text = nil, location = nil, language = nil)
-    RDoc::Comment.new(text, location, language).tap do |comment|
-      comment.format = @markup
-    end
+    RDoc::Comment.new(
+      text,
+      markup_source: location || @top_level,
+      language: language,
+      format: @markup
+    )
   end
 end
diff --git a/lib/rdoc/parser/changelog.rb b/lib/rdoc/parser/changelog.rb
index 802ac96f01..0ff9da1ae7 100644
--- a/lib/rdoc/parser/changelog.rb
+++ b/lib/rdoc/parser/changelog.rb
@@ -210,8 +210,12 @@ def scan
     grouped_entries = group_entries entries
 
     doc = create_document grouped_entries
-    comment = RDoc::Comment.new(@content)
-    comment.document = doc
+    doc.file = @top_level
+    comment = RDoc::Comment.from_document(
+      doc,
+      text: @content,
+      markup_source: @top_level
+    )
     @top_level.comment = comment
 
     @top_level
diff --git a/lib/rdoc/parser/markdown.rb b/lib/rdoc/parser/markdown.rb
index 3c316227b9..baf0b62958 100644
--- a/lib/rdoc/parser/markdown.rb
+++ b/lib/rdoc/parser/markdown.rb
@@ -13,8 +13,11 @@ class RDoc::Parser::Markdown < RDoc::Parser
   # Creates an Markdown-format TopLevel for the given file.
 
   def scan
-    comment = RDoc::Comment.new @content, @top_level
-    comment.format = 'markdown'
+    comment = RDoc::Comment.new(
+      @content,
+      markup_source: @top_level,
+      format: 'markdown'
+    )
 
     @top_level.comment = comment
   end
diff --git a/lib/rdoc/parser/rbs.rb b/lib/rdoc/parser/rbs.rb
index 1733b90d56..60bbd07a55 100644
--- a/lib/rdoc/parser/rbs.rb
+++ b/lib/rdoc/parser/rbs.rb
@@ -38,9 +38,8 @@ def rdoc_comment_for(decl)
 
     # TODO: Run RBS comments through RDoc's directive preprocessor so
     # directives like :nodoc: affect the documented object.
-    comment = RDoc::Comment.new rbs_comment.string, @top_level
-    comment.format = 'markdown'
-    comment
+    text = rbs_comment.string
+    RDoc::Comment.new(text, markup_source: @top_level, format: 'markdown')
   end
 
   def local_module_name(type_name, context)
@@ -80,10 +79,14 @@ def merge_comments(object, comment)
     document.concat comment.parse.parts
 
     # Keep this text separator in sync with the Rule node above.
-    merged_comment = RDoc::Comment.new "#{object.comment}\n---\n#{comment}", comment.location
-    merged_comment.format = 'markdown'
-    merged_comment.document = document
-    merged_comment
+    text = "#{object.comment}\n---\n#{comment}"
+    RDoc::Comment.from_document(
+      document,
+      text: text,
+      markup_source: comment.markup_source,
+      format: 'markdown',
+      normalized: true
+    )
   end
 
   def attr_rw_matches?(existing_rw, new_rw)
diff --git a/lib/rdoc/parser/rd.rb b/lib/rdoc/parser/rd.rb
index 19e47e549d..def97a7d6a 100644
--- a/lib/rdoc/parser/rd.rb
+++ b/lib/rdoc/parser/rd.rb
@@ -13,8 +13,11 @@ class RDoc::Parser::RD < RDoc::Parser
   # Creates an rd-format TopLevel for the given file.
 
   def scan
-    comment = RDoc::Comment.new @content, @top_level
-    comment.format = 'rd'
+    comment = RDoc::Comment.new(
+      @content,
+      markup_source: @top_level,
+      format: 'rd'
+    )
 
     @top_level.comment = comment
   end
diff --git a/lib/rdoc/parser/ruby.rb b/lib/rdoc/parser/ruby.rb
index c1c94f68f1..c46703dd2a 100644
--- a/lib/rdoc/parser/ruby.rb
+++ b/lib/rdoc/parser/ruby.rb
@@ -492,10 +492,10 @@ def process_comments_until(line_no_until)
     while !@unprocessed_comments.empty? && @unprocessed_comments.first[0] <= line_no_until
       line_no, start_line, text = @unprocessed_comments.shift
       if @markup == 'tomdoc'
-        comment = RDoc::Comment.new(text, @top_level, :ruby)
-        comment.format = 'tomdoc'
-        parse_comment_tomdoc(@container, comment, line_no, start_line)
+        comment = build_comment(text, start_line, 'tomdoc')
         @preprocess.run_post_processes(comment, @container)
+        comment.normalize
+        parse_comment_tomdoc(@container, comment, line_no, start_line)
       elsif (comment_text, directives = parse_comment_text_to_directives(text, start_line))
         handle_standalone_consecutive_comment_directive(comment_text, directives, text.start_with?(/#\#$/), line_no, start_line)
       end
@@ -526,21 +526,32 @@ def consecutive_comment(line_no)
   def parse_comment_text_to_directives(comment_text, start_line) # :nodoc:
     type_signature_lines = extract_type_signature!(comment_text, start_line)
     comment_text, directives = @preprocess.parse_comment(comment_text, start_line, :ruby)
-    comment = RDoc::Comment.new(comment_text, @top_level, :ruby)
-    comment.normalized = true
-    comment.line = start_line
     markup, = directives['markup']
-    comment.format = markup&.downcase || @markup
+    format = markup&.downcase || @markup
     if (section, directive_line = directives['section'])
       # If comment has :section:, it is not a documentable comment for a code object
-      comment.text = extract_section_comment(comment_text, directive_line - start_line)
+      comment_text = extract_section_comment(comment_text, directive_line - start_line)
+      comment = build_comment(comment_text, start_line, format, normalized: true)
       @container.set_current_section(section, comment)
       return
     end
+    comment = build_comment(comment_text, start_line, format, normalized: true)
     @preprocess.run_post_processes(comment, @container)
     [comment, directives, type_signature_lines]
   end
 
+  def build_comment(text, start_line, format, normalized: false) # :nodoc:
+    comment = RDoc::Comment.new(
+      text,
+      markup_source: @top_level,
+      language: :ruby,
+      format: format,
+      normalized: normalized
+    )
+    comment.line = start_line
+    comment
+  end
+
   # Extracts the comment for this section from the normalized comment block.
   # Removes all lines before the line that contains :section:
   # If the comment also ends with the same content, remove it as well
diff --git a/lib/rdoc/parser/simple.rb b/lib/rdoc/parser/simple.rb
index a0edca1b33..c235bda603 100644
--- a/lib/rdoc/parser/simple.rb
+++ b/lib/rdoc/parser/simple.rb
@@ -29,7 +29,7 @@ def initialize(top_level, content, options, stats)
   def scan
     content = remove_coding_comment @content
 
-    comment = RDoc::Comment.new content, @top_level
+    comment = RDoc::Comment.new(content, markup_source: @top_level)
 
     @top_level.comment = comment
     @top_level
diff --git a/lib/rdoc/ri/driver.rb b/lib/rdoc/ri/driver.rb
index 38ba18ea5d..581b955a31 100644
--- a/lib/rdoc/ri/driver.rb
+++ b/lib/rdoc/ri/driver.rb
@@ -1215,8 +1215,9 @@ 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}")
-    comment.parse
+    text = "missing documentation at #{e.file}"
+    markup_source = RDoc::TopLevel.new e.file
+    comment = RDoc::Comment.new(text, markup_source: markup_source)
 
     method = RDoc::AnyMethod.new name
     method.comment = comment
diff --git a/lib/rdoc/tom_doc.rb b/lib/rdoc/tom_doc.rb
index 64fb9ad972..88da7efa21 100644
--- a/lib/rdoc/tom_doc.rb
+++ b/lib/rdoc/tom_doc.rb
@@ -49,7 +49,7 @@ def self.add_post_processor # :nodoc:
       next unless code_object and
                   RDoc::Comment === comment and comment.format == 'tomdoc'
 
-      comment.text.gsub!(/\A(\s*# |)(Public|Internal|Deprecated):\s+/) do
+      comment.text = comment.text.gsub(/\A(\s*# |)(Public|Internal|Deprecated):\s+/) do
         section = code_object.add_section $2
         code_object.temporary_section = section
 
diff --git a/test/rdoc/code_object/class_module_test.rb b/test/rdoc/code_object/class_module_test.rb
index bff19a1513..11c35c20b7 100644
--- a/test/rdoc/code_object/class_module_test.rb
+++ b/test/rdoc/code_object/class_module_test.rb
@@ -9,19 +9,19 @@ def test_add_comment
     tl3 = @store.add_file 'three.rb'
 
     cm = RDoc::ClassModule.new 'Klass'
-    comment_tl1 = RDoc::Comment.new('# comment 1', @top_level, :ruby)
+    comment_tl1 = comment('# comment 1', tl1, :ruby)
     cm.add_comment comment_tl1, tl1
 
     assert_equal({ tl1 => [comment_tl1] }, cm.comment_location)
     assert_equal 'comment 1', cm.comment.text
 
-    comment_tl2 = RDoc::Comment.new('# comment 2', @top_level, :ruby)
+    comment_tl2 = comment('# comment 2', tl2, :ruby)
     cm.add_comment comment_tl2, tl2
 
     assert_equal({ tl1 => [comment_tl1], tl2 => [comment_tl2] }, cm.comment_location)
     assert_equal "comment 1\n---\ncomment 2", cm.comment
 
-    comment_tl3 = RDoc::Comment.new('# * comment 3', @top_level, :ruby)
+    comment_tl3 = comment('# * comment 3', tl3, :ruby)
     cm.add_comment comment_tl3, tl3
 
     assert_equal({ tl1 => [comment_tl1],
@@ -41,14 +41,16 @@ def test_add_comment_comment
   def test_add_comment_same_file_reopened_class
     tl1 = @store.add_file 'one.rb'
 
-    cm = RDoc::ClassModule.new 'Klass'
-    comment1 = RDoc::Comment.new('# comment 1', @top_level, :ruby)
-    comment2 = RDoc::Comment.new('# comment 2', @top_level, :ruby)
+    cm = tl1.add_class RDoc::NormalClass, 'Klass'
+    comment1 = comment('# comment 1', tl1, :ruby)
+    comment2 = comment('# comment 2', tl1, :ruby)
     cm.add_comment comment1, tl1
     cm.add_comment comment2, tl1
 
     # Both comments should appear in the rendered description
     assert_equal({ tl1 => [comment1, comment2] }, cm.comment_location)
+    assert_include cm.description, 'comment 1'
+    assert_include cm.description, 'comment 2'
   end
 
   def test_add_comment_stopdoc
@@ -68,15 +70,15 @@ def test_ancestors
 
   def test_comment_equals
     cm = RDoc::ClassModule.new 'Klass'
-    cm.comment = RDoc::Comment.new('# comment 1', @top_level, :ruby)
+    cm.comment = comment('# comment 1', @top_level, :ruby)
 
     assert_equal 'comment 1', cm.comment.to_s
 
-    cm.comment = RDoc::Comment.new('# comment 2', @top_level, :ruby)
+    cm.comment = comment('# comment 2', @top_level, :ruby)
 
     assert_equal "comment 1\n---\ncomment 2", cm.comment.to_s
 
-    cm.comment = RDoc::Comment.new('# * comment 3', @top_level, :ruby)
+    cm.comment = comment('# * comment 3', @top_level, :ruby)
 
     assert_equal "comment 1\n---\ncomment 2\n---\n* comment 3", cm.comment.to_s
   end
@@ -128,6 +130,18 @@ def test_documented_eh
     assert cm.documented?, ':nodoc:'
   end
 
+  def test_description_with_locale
+    locale = RDoc::I18n::Locale.new 'fr'
+    locale.instance_variable_get(:@messages)['comment'] = 'commentaire'
+    @options.locale = locale
+
+    top_level = @store.add_file 'one.rb'
+    class_module = top_level.add_class RDoc::NormalClass, 'Klass'
+    class_module.add_comment 'comment', top_level
+
+    assert_include class_module.description, 'commentaire'
+  end
+
   def test_each_ancestor
     assert_equal [@parent, @object], @child.each_ancestor.to_a
   end
@@ -186,8 +200,7 @@ def test_marshal_dump
     e1 = RDoc::Extend.new 'E1', ''
     e1.record_location tl
 
-    section_comment = RDoc::Comment.new('section comment')
-    section_comment.location = tl
+    section_comment = comment 'section comment', tl
 
     assert_equal 1, cm.sections.length, 'sanity, default section only'
     s0 = cm.sections.first
@@ -267,9 +280,6 @@ def test_marshal_dump_visibility
     e1.record_location tl
     e1.document_self = false
 
-    section_comment = RDoc::Comment.new('section comment')
-    section_comment.location = tl
-
     assert_equal 1, cm.sections.length, 'sanity, default section only'
 
     cm.add_attribute a1
@@ -537,8 +547,7 @@ def test_marshal_load_version_3
     e1 = RDoc::Extend.new 'E1', ''
     e1.record_location tl
 
-    section_comment = RDoc::Comment.new('section comment')
-    section_comment.location = tl
+    section_comment = comment 'section comment', tl
 
     assert_equal 1, cm.sections.length, 'sanity, default section only'
     s0 = cm.sections.first
@@ -1168,7 +1177,7 @@ def test_merge_sections_overlap
     assert_equal expected, comments.sort_by { |c| c.file.name }
   end
 
-  def test_parse
+  def test_parse_comment_locations
     tl1 = @store.add_file 'one.rb'
     tl2 = @store.add_file 'two.rb'
 
@@ -1183,7 +1192,7 @@ def test_parse
 
     expected = @RM::Document.new doc1, doc2
 
-    assert_equal expected, cm.parse(cm.comment_location)
+    assert_equal expected, cm.parse_comment_locations(cm.comment_location)
   end
 
   def test_parse_comment
@@ -1195,7 +1204,9 @@ def test_parse_comment
     doc = @RM::Document.new @RM::Paragraph.new 'comment 1'
     doc.file = tl1
 
-    assert_equal doc, cm.parse(cm.comment)
+    parsed = cm.comment.parse
+    assert_equal doc, parsed
+    assert_same parsed, cm.parse(cm.comment)
   end
 
   def test_parse_comment_format
@@ -1211,7 +1222,7 @@ def test_parse_comment_format
     assert_equal doc, cm.parse(cm.comment)
   end
 
-  def test_parse_comment_location
+  def test_parse_comment_locations_after_marshal
     tl1 = @store.add_file 'one.rb'
     tl2 = @store.add_file 'two.rb'
 
@@ -1229,8 +1240,7 @@ def test_parse_comment_location
     # After marshal, comment_location should still be a hash
     assert_kind_of Hash, cm.comment_location
 
-    # parse() produces a Document with parts for each comment
-    parsed = cm.parse(cm.comment_location)
+    parsed = cm.parse_comment_locations(cm.comment_location)
     assert_kind_of RDoc::Markup::Document, parsed
     assert_equal 2, parsed.parts.length
     assert_equal 'comment 1', parsed.parts[0].parts[0].text
diff --git a/test/rdoc/generator/darkfish_test.rb b/test/rdoc/generator/darkfish_test.rb
index 966a8f2d2e..89707c4c37 100644
--- a/test/rdoc/generator/darkfish_test.rb
+++ b/test/rdoc/generator/darkfish_test.rb
@@ -564,8 +564,7 @@ def test_meta_tags_for_markdown_files
 
   def test_meta_tags_for_raw_pages
     top_level = @store.add_file("MyPage", parser: RDoc::Parser::Simple)
-    comment = RDoc::Comment.new('this is a comment')
-    comment.document = RDoc::Markup::Document.new(RDoc::Markup::Paragraph.new('this is a comment'))
+    comment = self.comment 'this is a comment', top_level
     top_level.comment = comment
 
     @g.generate
diff --git a/test/rdoc/markup/pre_process_test.rb b/test/rdoc/markup/pre_process_test.rb
index d8367a4c04..70c183abb1 100644
--- a/test/rdoc/markup/pre_process_test.rb
+++ b/test/rdoc/markup/pre_process_test.rb
@@ -10,6 +10,7 @@ def setup
     @tempfile = Tempfile.new 'test_rdoc_markup_pre_process'
     @file_name = File.basename @tempfile.path
     @dir  = File.dirname @tempfile.path
+    @top_level = @store.add_file @tempfile.path
 
     @pp = RDoc::Markup::PreProcess.new @tempfile.path, [@dir, File.expand_path('..', File.dirname(__FILE__))]
   end
diff --git a/test/rdoc/parser/c_test.rb b/test/rdoc/parser/c_test.rb
index c2b92ae053..5b91ec8f11 100644
--- a/test/rdoc/parser/c_test.rb
+++ b/test/rdoc/parser/c_test.rb
@@ -1562,7 +1562,7 @@ def test_find_body_static_inline
   end
 
   def test_find_modifiers_call_seq
-    comment = RDoc::Comment.new <<~COMMENT
+    comment = self.comment <<~COMMENT
       call-seq:
         commercial() -> Date <br />
 
@@ -1579,7 +1579,7 @@ def test_find_modifiers_call_seq
   end
 
   def test_find_modifiers_nodoc
-    comment = RDoc::Comment.new <<~C
+    comment = self.comment <<~C
       /* :nodoc:
        *
        * Blah
@@ -1596,7 +1596,7 @@ def test_find_modifiers_nodoc
   end
 
   def test_find_modifiers_yields
-    comment = RDoc::Comment.new <<~C, @top_level, :c
+    comment = self.comment <<~C, @top_level, :c
       /* :yields: a, b
        *
        * Blah
@@ -1733,7 +1733,7 @@ def test_handle_singleton
   def test_look_for_directives_in
     parser = util_parser
 
-    comment = RDoc::Comment.new "* :other: not_handled\n"
+    comment = self.comment "* :other: not_handled\n"
 
     parser.look_for_directives_in @top_level, comment
 
diff --git a/test/rdoc/parser/rbs_test.rb b/test/rdoc/parser/rbs_test.rb
index 0365462cc1..4b1aed427d 100644
--- a/test/rdoc/parser/rbs_test.rb
+++ b/test/rdoc/parser/rbs_test.rb
@@ -44,6 +44,7 @@ def greet: (String) -> Integer
     greet = sample.find_method 'greet', false
     assert_equal ['(String) -> Integer', '(Symbol) -> String'], greet.type_signature_lines
     assert_equal 'Greets by name.', greet.comment.text.strip
+    assert_same @top_level, greet.comment.markup_source
     assert_same @top_level, greet.comment.location
     assert_equal 'sample.rbs', greet.comment.parse.file
 
@@ -140,6 +141,7 @@ def greet: () -> String
 
     assert_equal "Ruby class docs.\n---\nRBS class docs.", sample.comment.to_s.strip
     assert_equal "Ruby method docs.\n---\nRBS method docs.", greet.comment.to_s.strip
+    assert_same @top_level, greet.comment.markup_source
     assert_equal ['() -> String'], greet.type_signature_lines
   end
 
diff --git a/test/rdoc/parser/ruby_test.rb b/test/rdoc/parser/ruby_test.rb
index 17cd9ea8c0..1865968109 100644
--- a/test/rdoc/parser/ruby_test.rb
+++ b/test/rdoc/parser/ruby_test.rb
@@ -17,7 +17,7 @@ def setup
     @options.quiet = true
     @options.option_parser = OptionParser.new
 
-    @comment = RDoc::Comment.new '', @top_level
+    @comment = comment '', @top_level
 
     @stats = RDoc::Stats.new @store, 0
   end
@@ -2419,8 +2419,8 @@ module Foo
     mod = @top_level.modules.first
 
     expected = [
-      RDoc::Comment.new('comment a', @top_level),
-      RDoc::Comment.new('comment b', @top_level)
+      comment('comment a', @top_level),
+      comment('comment b', @top_level)
     ]
 
     assert_equal expected, mod.comment_location[@top_level]
@@ -2749,7 +2749,20 @@ def m2; end
 
     assert_equal 'rdoc', c.comment.format
 
-    assert_equal ['rd', 'rdoc'], c.method_list.map { |m| m.comment.format }
+    comments = c.method_list.map(&:comment)
+    assert_equal ['rd', 'rdoc'], comments.map(&:format)
+    comments.each do |comment|
+      assert_same @top_level, comment.markup_source
+      assert_nil comment.instance_variable_get(:@document)
+    end
+
+    expected = doc para('<em>radical</em>')
+    expected.file = @top_level
+    first_document, second_document = comments.map(&:parse)
+    assert_equal expected, first_document
+    assert_not_same first_document, second_document
+    assert_equal @top_level.relative_name, first_document.file
+    assert_equal @top_level.relative_name, second_document.file
   end
 
   def test_tomdoc_meta
@@ -2806,6 +2819,8 @@ def m2; end
     assert_equal 'Internal', m2.section.title
     assert_equal "foo\nbar", m1.comment.text.chomp
     assert_equal "baz\nblah", m2.comment.text.chomp
+
+    assert_equal 'foo bar', m1.comment.parse.parts.first.text
   end
 
   def test_various_callseq
diff --git a/test/rdoc/rdoc_comment_test.rb b/test/rdoc/rdoc_comment_test.rb
index 8fa5e281fb..e086e18902 100644
--- a/test/rdoc/rdoc_comment_test.rb
+++ b/test/rdoc/rdoc_comment_test.rb
@@ -9,9 +9,7 @@ def setup
     super
 
     @top_level = @store.add_file 'file.rb'
-    @comment = RDoc::Comment.new
-    @comment.location = @top_level
-    @comment.text = 'this is a comment'
+    @comment = comment 'this is a comment'
   end
 
   def test_empty
@@ -35,8 +33,8 @@ def test_equals2
 
     refute_equal @comment, c2
 
-    c3 = @comment.dup
-    c3.location = nil
+    other_top_level = @store.add_file 'other.rb'
+    c3 = comment @comment.text, other_top_level
 
     refute_equal @comment, c3
   end
@@ -47,6 +45,15 @@ def test_force_encoding
     assert_equal Encoding::UTF_8, @comment.text.encoding
   end
 
+  def test_force_encoding_preserves_document
+    document = @RM::Document.new @RM::Paragraph.new('loaded comment')
+    comment = RDoc::Comment.from_document document
+
+    RDoc::Encoding.change_encoding comment, Encoding::UTF_8
+
+    assert_same document, comment.parse
+  end
+
   def test_format
     assert_equal 'rdoc', @comment.format
   end
@@ -54,22 +61,57 @@ def test_format
   def test_format_equals
     c = comment 'content'
     document = c.parse
+    markup_source = c.markup_source
 
     c.format = RDoc::RD
 
     assert_equal RDoc::RD, c.format
     refute_same document, c.parse
+    assert_same markup_source, c.markup_source
   end
 
   def test_initialize_copy
     copy = @comment.dup
 
     refute_same @comment.text, copy.text
+    assert_same @comment.markup_source, copy.markup_source
     assert_same @comment.location, copy.location
   end
 
+  def test_markup_source
+    assert_same @top_level, @comment.markup_source
+  end
+
+  def test_markup_source_from_document
+    document = @RM::Document.new @RM::Paragraph.new('this is a comment')
+
+    comment = RDoc::Comment.from_document document
+
+    assert_same document, comment.markup_source
+    assert_same document, comment.parse
+    assert_nil comment.location
+  end
+
+  def test_markup_source_from_document_with_file
+    document = @RM::Document.new @RM::Paragraph.new('this is a comment')
+    document.file = @top_level
+
+    comment = RDoc::Comment.from_document document
+
+    assert_equal @top_level, comment.markup_source
+    assert_same document, comment.parse
+  end
+
   def test_location
-    assert_equal @top_level, @comment.location
+    assert_same @comment.markup_source, @comment.location
+  end
+
+  def test_parse_is_lazy
+    assert_nil @comment.instance_variable_get(:@document)
+
+    document = @comment.parse
+
+    assert_same document, @comment.instance_variable_get(:@document)
   end
 
   def test_normalize
@@ -98,8 +140,7 @@ def test_normalize_twice
   end
 
   def test_normalize_document
-    @comment.text = nil
-    @comment.document = @RM::Document.new
+    @comment = RDoc::Comment.from_document(@RM::Document.new, text: nil)
 
     assert_same @comment, @comment.normalize
 
@@ -118,6 +159,12 @@ def test_text
     assert_equal 'this is a comment', @comment.text
   end
 
+  def test_to_s_document_only
+    comment = RDoc::Comment.from_document(@RM::Document.new, text: nil)
+
+    assert_nil comment.to_s
+  end
+
   def test_text_equals
     @comment.text = 'other'
 
@@ -126,8 +173,7 @@ def test_text_equals
   end
 
   def test_text_equals_no_text
-    c = RDoc::Comment.new nil, @top_level
-    c.document = @RM::Document.new
+    c = RDoc::Comment.from_document(@RM::Document.new, text: nil)
 
     e = assert_raise RDoc::Error do
       c.text = 'other'
@@ -138,10 +184,12 @@ def test_text_equals_no_text
 
   def test_text_equals_parsed
     document = @comment.parse
+    markup_source = @comment.markup_source
 
     @comment.text = 'other'
 
     refute_equal document, @comment.parse
+    assert_same markup_source, @comment.markup_source
   end
 
   def test_tomdoc_eh
diff --git a/test/rdoc/rdoc_context_section_test.rb b/test/rdoc/rdoc_context_section_test.rb
index a3d9930638..808b584fdc 100644
--- a/test/rdoc/rdoc_context_section_test.rb
+++ b/test/rdoc/rdoc_context_section_test.rb
@@ -19,9 +19,9 @@ def test_add_comment
 
     klass = file1.add_class RDoc::NormalClass, 'Klass'
 
-    c1 = RDoc::Comment.new "",       file1
-    c2 = RDoc::Comment.new "# hello\n", file1
-    c3 = RDoc::Comment.new "# world\n", file1
+    c1 = comment "",       file1
+    c2 = comment "# hello\n", file1
+    c3 = comment "# world\n", file1
 
     s = @S.new klass, 'section', c1
 
@@ -94,7 +94,7 @@ def test_hash
   def test_marshal_dump
     loaded = Marshal.load Marshal.dump @s
 
-    expected = doc RDoc::Comment.new('comment', @top_level).parse
+    expected = doc comment('comment', @top_level).parse
 
     assert_equal 'section', loaded.title
     assert_equal expected,  loaded.to_document
@@ -120,7 +120,7 @@ def test_marshal_load_version_0
                           "[\x06I\"\fcomment\x06;\x06F:\n@fileI" +
                           "\"\ffile.rb\x06;\x06F;\n0"
 
-    expected = doc RDoc::Comment.new('comment', @top_level).parse
+    expected = doc comment('comment', @top_level).parse
 
     assert_equal 'section', loaded.title
     assert_equal expected,  loaded.to_document
diff --git a/test/rdoc/rdoc_context_test.rb b/test/rdoc/rdoc_context_test.rb
index 04f84ed433..5b86c7510e 100644
--- a/test/rdoc/rdoc_context_test.rb
+++ b/test/rdoc/rdoc_context_test.rb
@@ -395,7 +395,7 @@ def test_add_to_temporary_section
     incl = RDoc::Include.new 'Name', 'comment'
     arr = []
     section =
-      @context.add_section 'temporary', RDoc::Comment.new('', @top_level)
+      @context.add_section 'temporary', comment('', @top_level)
     @context.temporary_section = section
 
     @context.add_to arr, incl
@@ -462,7 +462,7 @@ def test_current_section
     default_section = @context.current_section
 
     new_section =
-      @context.add_section 'other', RDoc::Comment.new('', @top_level)
+      @context.add_section 'other', comment('', @top_level)
     @context.temporary_section = new_section
 
     assert_equal new_section, @context.current_section
@@ -882,11 +882,11 @@ def test_section_contents_unused
   def test_set_current_section
     default_section = @context.sections.first
 
-    @context.set_current_section nil, RDoc::Comment.new('', @top_level)
+    @context.set_current_section nil, comment('', @top_level)
 
     assert_equal default_section, @context.current_section
 
-    @context.set_current_section 'other', RDoc::Comment.new('', @top_level)
+    @context.set_current_section 'other', comment('', @top_level)
 
     new_section = @context.sections.find { |section|
       section != default_section
diff --git a/test/rdoc/rdoc_stats_test.rb b/test/rdoc/rdoc_stats_test.rb
index ea2b851b38..22e93c5e68 100644
--- a/test/rdoc/rdoc_stats_test.rb
+++ b/test/rdoc/rdoc_stats_test.rb
@@ -8,7 +8,7 @@ def setup
 
     @s = RDoc::Stats.new @store, 0
 
-    @tl = @store.add_file 'file.rb'
+    @top_level = @tl = @store.add_file 'file.rb'
     @tl.parser = RDoc::Parser::Ruby
   end
 
diff --git a/test/rdoc/rdoc_store_test.rb b/test/rdoc/rdoc_store_test.rb
index 34e3ade60a..cce2811f9e 100644
--- a/test/rdoc/rdoc_store_test.rb
+++ b/test/rdoc/rdoc_store_test.rb
@@ -14,7 +14,7 @@ def setup
     @top_level = @s.add_file 'file.rb'
 
     @page = @s.add_file 'README.txt', parser: RDoc::Parser::Simple
-    @page.comment = RDoc::Comment.new 'This is a page', @page
+    @page.comment = comment 'This is a page', @page
 
     @klass = @top_level.add_class RDoc::NormalClass, 'Object'
     @klass.add_comment 'original', @top_level
@@ -23,8 +23,7 @@ def setup
     @cmeth = RDoc::AnyMethod.new 'cmethod', singleton: true
     @cmeth.record_location @top_level
 
-    @meth_comment = RDoc::Comment.new 'method comment'
-    @meth_comment.location = @top_level
+    @meth_comment = comment 'method comment', @top_level
 
     @meth = RDoc::AnyMethod.new 'method'
     @meth.record_location @top_level
@@ -38,8 +37,7 @@ def setup
 
     @meth_bang.add_alias @meth_bang_alias, @klass
 
-    @attr_comment = RDoc::Comment.new 'attribute comment'
-    @attr_comment.location = @top_level
+    @attr_comment = comment 'attribute comment', @top_level
 
     @attr = RDoc::Attr.new 'attr', 'RW', ''
     @attr.record_location @top_level
diff --git a/test/rdoc/rdoc_tom_doc_test.rb b/test/rdoc/rdoc_tom_doc_test.rb
index 3446e3d05c..e4e6fa8c14 100644
--- a/test/rdoc/rdoc_tom_doc_test.rb
+++ b/test/rdoc/rdoc_tom_doc_test.rb
@@ -19,8 +19,7 @@ def test_class_add_post_processor
 
     text = "# Public: Do some stuff\n"
 
-    comment = RDoc::Comment.new text, nil
-    comment.format = 'tomdoc'
+    comment = self.comment text, @top_level, format: 'tomdoc'
 
     parent = RDoc::Context.new
 
diff --git a/test/rdoc/rdoc_top_level_test.rb b/test/rdoc/rdoc_top_level_test.rb
index c857f16395..07bf20d866 100644
--- a/test/rdoc/rdoc_top_level_test.rb
+++ b/test/rdoc/rdoc_top_level_test.rb
@@ -207,7 +207,7 @@ def test_path_non_main_page_unaffected
   def test_marshal_dump
     page = @store.add_file 'README.txt'
     page.parser = RDoc::Parser::Simple
-    page.comment = RDoc::Comment.new 'This is a page', page
+    page.comment = comment 'This is a page', page
 
     loaded = Marshal.load Marshal.dump page
 
diff --git a/test/rdoc/support/test_case.rb b/test/rdoc/support/test_case.rb
index 99af043991..bf790ee31b 100644
--- a/test/rdoc/support/test_case.rb
+++ b/test/rdoc/support/test_case.rb
@@ -111,9 +111,13 @@ def block(*contents)
   # Creates an RDoc::Comment with +text+ which was defined on +top_level+.
   # By default the comment has the 'rdoc' format.
 
-  def comment(text, top_level = @top_level, language = nil)
-    comment = RDoc::Comment.new text, top_level, language
-    comment
+  def comment(text, top_level = @top_level, language = nil, format: 'rdoc')
+    RDoc::Comment.new(
+      text,
+      markup_source: top_level,
+      language: language,
+      format: format
+    )
   end
 
   ##