Document is not a Comment. Document shouldn't be assigned to code_object.comment

[tompng]

CodeObject#comment is normally String or Comment, but Marshal dump and load creates CodeObject with Document as a comment. So there are two types of CodeObject that shouldn't be mixed:

• ParsedCodeObject: comment is a String or a Comment
• MarshalLoadedCodeObject: comment is a Document

This is implicitly doubling the number of total classes in RDoc. It is mixing huge complexity and potential bugs to RDoc codebase. Some method only accepts ParsedCodeObject. Some method only accepts MarshalLoadedCodeObject. It is difficult to know.

def add_extension_modules_single out, store, include
  # include should be RDoc::Markup::(MarshalLoaded)Include. Does not accept RDoc::Markup::(Parsed)Include
  ...
  out << RDoc::Markup::BlankLine.new
  out << include.comment
end

It looks like document is assigned to comment to represent parse-result-cached comment. Alternatively, Comment#document= can be used to represent it.

Ideally, we should avoid mixing String with Comment, but String it is too frequently used. I think it will be easy to remove mixing String after switching to PrismRuby Parser.

I believe we should do this refactor someday but maybe not before Ruby 3.4 because the release date is pretty close.