Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix section comments (in darkfish) #936

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

nevans
Copy link
Contributor

@nevans nevans commented Oct 14, 2022

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
Copy link
Member

nobu commented Oct 15, 2022

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
Copy link
Contributor Author

nevans commented Oct 16, 2022

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
Copy link
Contributor Author

nevans commented Oct 16, 2022

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
Copy link
Contributor Author

nevans commented Oct 24, 2022

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 nevans marked this pull request as draft November 22, 2022 17:20
@nevans
Copy link
Contributor Author

nevans commented Nov 22, 2022

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

This is almost certainly the wrong way to do this.  But the lack of
section comments has been bugging me for years, and this was my first
attempt at figuring out why it is broken.  Maybe someone else can fix it
The Right Way, or give me some advice on how to do so myself...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants