[#104004] [Ruby master Feature#17883] Load bundler/setup earlier to make `bundle exec ruby -r` respect Gemfile — mame@...
Issue #17883 has been reported by mame (Yusuke Endoh).
21 messages
2021/05/24
[ruby-core:104047] [Ruby master Misc#17888] "What's Here" section for class and module documentation
From:
burdettelamar@...
Date:
2021-05-25 18:49:32 UTC
List:
ruby-core #104047
Issue #17888 has been reported by [email protected] (Burdette Lamar). ---------------------------------------- Misc #17888: "What's Here" section for class and module documentation https://bugs.ruby-lang.org/issues/17888 * Author: [email protected] (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:[email protected]?subject=unsubscribe> <http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>