Project

General

Profile

Actions

Misc #17888

closed

"What's Here" section for class and module documentation

Added by burdettelamar@yahoo.com (Burdette Lamar) 4 months ago. Updated 3 months ago.

Status:
Closed
Priority:
Normal
Assignee:
-
[ruby-core:104047]

Description

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.

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?
Actions

Also available in: Atom PDF