From: chris@... Date: 2021-05-26T13:06:41+00:00 Subject: [ruby-core:104056] [Ruby master Misc#17888] "What's Here" section for class and module documentation Issue #17888 has been updated by 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? ---------------------------------------- Misc #17888: "What's Here" section for class and module documentation https://bugs.ruby-lang.org/issues/17888#change-92198 * 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: