Issue #17888 has been updated by 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, 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.

----------------------------------------
Misc #17888: "What's Here" section for class and module documentation
https://bugs.ruby-lang.org/issues/17888#change-92564

* Author: burdettelamar / yahoo.com (Burdette Lamar)
* Status: Closed
* Priority: Normal
----------------------------------------
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](https://docs.ruby-lang.org/en/master/Array.html#class-Array-label-What-27s+Here)
- [BasicObject](https://docs.ruby-lang.org/en/master/BasicObject.html#class-BasicObject-label-What-27s+Here)
- [Dir](https://docs.ruby-lang.org/en/master/Dir.html#class-Dir-label-What-27s+Here)
- [Enumerable](https://docs.ruby-lang.org/en/master/Enumerable.html#module-Enumerable-label-What-27s+Here)
- [File](https://docs.ruby-lang.org/en/master/File.html#class-File-label-What-27s+Here)
- [Hash](https://docs.ruby-lang.org/en/master/Hash.html#class-Hash-label-What-27s+Here)
- [IO](https://docs.ruby-lang.org/en/master/IO.html#class-IO-label-What-27s+Here)
- [Kernel](https://docs.ruby-lang.org/en/master/Kernel.html#module-Kernel-label-What-27s+Here)
- [Object](https://docs.ruby-lang.org/en/master/Object.html#class-Object-label-What-27s+Here)
- [Set](https://docs.ruby-lang.org/en/master/Set.html#class-Set-label-What-27s+Here)
- [String](https://docs.ruby-lang.org/en/master/String.html#class-String-label-What-27s+Here)
- [Time](https://docs.ruby-lang.org/en/master/Time.html#class-Time-label-What-27s+Here)

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?




-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>