Fix sections not displaying their text

[Earlopain]

I'm currently trying to group methods in the prism docs by topic like "location related", " flag related", etc. so that methods not related to these conceps show up more prominently (not mixed in with potentially many other methods). But I noticed that sections do not currently show their comment.

There were a few things wrong that made this not work:

• Formatting expects @comment but there is only @comments
• The parse method used for marshaling overwrote the markdown parse method
• @store was not present, which the formatter requires

Comments can be added/removed, so there still needs to be the array to make it possible to properly modify the section.

Fixes #345, Closes #936

On https://docs.ruby-lang.org/en/master/Prism/Node.html#node-interface there is actually already a comment but it gets swallowed. With this change, it gets properly rendered:

[tompng]

This will double-normalize a comment if comment is already normalized.

# :section: Foo
# # aaa (should be "# aaa")

RDoc::Text#markup will accept RDoc::Comment, so we don't need to use comment.text.
Instead of overriding markup, how about overriding description like this?

def description
   markup comment if @comments.any?
end

For reference, RDoc::ClassModule overrides description too

class RDoc::ClassModule

  ##
  # Handy wrapper for marking up this class or module's comment

  def description
    markup @comment_location
  end

end

[Earlopain]

Works nicely, thanks

[tompng]

If a section comment is separated, I think it should be separated with <p> tag.

# Document1
class A
end

# Document2
class A
end

will generate

<h1 id="class-a" class="anchor-link class">class A</h1>
<section class="description">
<p>Foo</p>
<p>Bar</p>
</section>

So

class A
  # :section: Section1
  # hello

  # :section: Section1
  # world
end

is better to generate

<p>hello</p><p>world</p>

One way to create a normalized separated comment is to use:

RDoc::Comment.from_document(to_document)

This will create a concatenated normalized comment. comment.text is nil, and the parsed result comment.instance_variable_get(:@document) is present.

[tompng]

I think using both @comments and @comment is not so great.
Renaming this method to comment, just return a comment without storing to @comment will make the state of this class more simple, I think. To do this, we need to modify def description.

[Earlopain]

👍, I applied your suggestion and it's a bit cleaner now.

I removed the tests I added about comment in test_add_comment. Since from_document always sets the comment text to the empty string, they don't hold anymore. I'm not sure how it works but it seems to work out in the end.

[matzbot]

🚀 Preview deployment available at: https://e227b50d.rdoc-6cd.pages.dev (commit: dfb71ee)