"What's Here" section for class and module documentation
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:
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.
- 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?