Issue #17888 has been reported by burdettelamar / yahoo.com (Burdette Lamar).

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

* Author: burdettelamar / yahoo.com (Burdette Lamar)
* Status: Open
* 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>