Fix section comments (in darkfish)

[nevans]

The lack of section comments has been annoying me for couple of years, and this was my first attempt at figuring out why it is broken. This fixes it! 🎉

n.b. this PR in its current form probably shouldn't be accepted: no tests, and the way I fixed it feels like a hack. But I don't grok the codebase well enough to know what I'm meant to be doing instead. I was basically just stumbling my way through the code with pry and debugger and $stderr.puts until I got something that worked!

Hopefully this helps someone else fix it the right way. Or let me know what I should do to make this PR acceptable. Thanks!

[nobu]

Sorry, I can't get your point.

• Is this a proposal of a new feature?
• what do you mean by "section comments"?
• what will be achieved by this PR?

[nevans]

My apologies. I was in a rush when I posted this. I'm talking about the text that comes after :section: Section Name. The documentation in RDoc::Markup also calls it "introductory text".

As far as I can tell, rdoc always saves that text onto section.comments (plural). And the darkfish template has code that prints out section.comment (singular). But the section.comment attribute is always empty, as far as I can tell. Therefore the section's introductory text is never rendered, even though the template is clearly trying to render it.

From https://docs.ruby-lang.org/en/3.1/RDoc/Markup.html#class-RDoc::Markup-label-Sections, I'm referring to this:

:section: title

Provides section introductory text in RDoc output. The title following :section: is used as the section name and the remainder of the comment containing the section is used as introductory text. A section’s comment block must be separated from following comment blocks. Use an empty title to switch to the default section.

...

Example:

# ----------------------------------------
# :section: My Section
# This is the section that I wrote.
# See it glisten in the noon-day sun.
# ----------------------------------------

[nevans]

and I also want to repeat: this PR in its current form shouldn't be accepted. It has no tests, and I was in a hurry, so I submitted it immediately after I had figured out the problem. I wanted feedback about how I (or someone else) should fix it "properly". Thanks!

[nevans]

n.b. the section description is also mentioned in doc/rdoc/markup_reference.rb:

The comment block containing this directive:

• Must be separated by a blank line from the documentation for the next item.
• May have one or more lines preceding the directive. These will be removed, along with any trailing lines that match them. Such lines may be visually helpful.
• Lines of text that are not so removed become the descriptive text for the section.

(emphasis is mine)

Unfortunately, although the descriptive text makes this claim, the MarkupReference class never demonstrates it... because it can't until the bug is fixed. 🙂

[nevans]

I've converted this to a "Draft" because I don't think it should be accepted as-is.

I used a monkey-patch for the same affect here: https://github.com/ruby/net-imap/blob/d59fb98b8c29e77fdd5935aae35a7e3d151c562d/rakelib/rdoc.rake#L15-L24 and https://github.com/ruby/net-imap/blob/d59fb98b8c29e77fdd5935aae35a7e3d151c562d/rakelib/rdoc.rake#L54-L56

And here is a demonstration of section comments output: https://nevans.github.io/net-imap/Net/IMAP.html#Basic+Mailbox+Attributes