Fix comment location marshalling in ClassModule

[st0012]

Fixes #1523

The issue is likely caused by RDoc generating documentation using data from marshal load (used by ri), which has different types than if the generation happen directly.

This code can reproduce the same error:

require 'rdoc'
require 'tmpdir'

# Setup store
options = RDoc::Options.new
store = RDoc::Store.new(options, path: Dir.tmpdir)

# Create a class with a comment
tl = store.add_file 'file.rb'
ns = tl.add_module RDoc::NormalModule, 'Namespace'
cm = ns.add_class RDoc::NormalClass, 'Klass', 'Super'
cm.add_comment 'This is a class comment', tl

# Before marshalling - works fine
puts "Before marshal: #{cm.search_snippet.inspect}"

# Marshal round-trip (simulates loading from .ri cache)
loaded = Marshal.load(Marshal.dump(cm))
loaded.store = store

# After marshalling - fails with NoMethodError
puts "After marshal: #{loaded.search_snippet.inspect}"

Similar to other code objects' marshalling behaviour, ClassModule#comment_location's content type would change before/after marshalling. But it should still be an array of pairs that respond to the same set of methods.

This commit also adds documentation about the marshalling behaviour of ClassModule#comment_location.

I don't like the fact that data types & shapes could change before/after marshalling. But changing this design will be a breaking change and require some careful planning. So for now the change it to make sure the type change is less surprising

[matzbot]

🚀 Preview deployment available at: https://30718c1a.rdoc-6cd.pages.dev (commit: 99eef47)

[vinistock]

We were creating a brand new document before. Was that intentional?

For example, should the updated code be this?

new_doc = RDoc::Markup::Document.new document
[[new_doc, new_doc.file]]

[tompng]

document is not a comment, so I think it should ideally be [[comment, document.file]] for both branch.

@comment_locaation = [[comment, document.file]]

parse([[@comment, document.file]]) will return a parsed document cached in @comment (as attr_reader :document)

Although not fully investigated the effect of doing this.

[tompng]

Since parse @comment_location seems working, I'm OK with the less-impact change: [[document, location]] for now 👍