search

ruby / rdoc

RDoc produces HTML and online documentation for Ruby projects.
https://ruby.github.io/rdoc/
Other
844 stars 440 forks source link

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

Open tompng opened 1 week ago

tompng commented 1 week ago

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:

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.