Misc #17888: "What's Here" section for class and module documentation

• Status: Closed
• Assignee: -

Proposed: That a "What's Here" section is a useful enhancement to the documentation for a class or module.

Actually, this work is already begun; these are already merged into master:

• Array
• BasicObject
• Dir
• Enumerable
• File
• Hash
• IO
• Kernel
• Object
• Set
• String
• Time

My intentions for these sections are to:

• Emphasize "what's elsewhere," by listing the parent class and each included module, and linking to the documentation for each of those.
• Provide an overview of the class or module via a 1-line synopsis of each method, with a link to its documentation.

Some reservations have been expressed:

• The section is redundant. [Me] True enough; it's a summary.
• The section may have a limited audience, being most useful to a new Ruby user. [Me] Also useful to any newcomer to the class or module, and to anyone who can profit from an overview.
• The section may not be maintained properly (each synopsis being separated from the method's own documentation). [Me] Again, true enough. But that's also true of all the (overview) documentation for the class or module.
• Each synopsis should be embedded in the method's own documentation. RDoc itself should extract the data, then assemble and insert the section. [Me] Completely agree, but far out of scope for me.

Questions:

• Do we want to have "What's Here" sections?
• If so:
  • Is the current format of the "What's Here" sections acceptable, or should it be modified?
  • Do we want to work on changes to RDoc such that the content in "What's Here" sections is stored with the method documentation?

[chrisseaton (Chris Seaton)]

It's always great when someone volunteers to work on documentation!

But doesn't the documentation already have a table-of-contents for each class? I see it down the left-hand-side here.

https://docs.ruby-lang.org/en/master/Array.html

Your new table-of-contents is really buried after a huge amount of text. I think it's about a tenth of the way down the page? I don't think many people would even see it to know it's there!

The one-line-summary is useful - but couldn't that be added to the existing table-of-contents rather than creating a second table-of-contents? It could be metadata in the main documentation and pulled out by RDoc. Likewise for the sections. People have said to me 'but that would require modifying RDoc' - isn't a little patch to RDoc preferable to lots of manual editing?

[mame (Yusuke Endoh)]

• Status changed from Open to Closed

We discussed this ticket in today's dev-meeting.

Many committers agreed that the categorized method list with one-line summary is good to have. The traditional name-only list is in ABC order, which is less useful.

It is definitely better if rdoc provides a category feature to group methods by kinds. @aycabta (aycabta .), who is a current active maintainer of rdoc, said that he would investigate other documenting systems (like yard) and try to support the feature.

Manual editing is indeed suboptimal, but at the present time, there is no other way until rdoc is improved. So please continue to work. Note that, if the concern about maintenance becomes a reality, we may have to delete the summary. We hope rdoc supports method category feature in near future.