From: "Suraj N. Kurapati" <sunaku@...>
Date: 2008-05-09T00:54:11+09:00
Subject: Re: Uniform RDoc markup - automatic require() section

Jeremy McAnally wrote:
> The main lack I see in the stdlib is the lack of examples for a number
> of things and some things not being doc'd at all.

I suppose this would fall under examples, but the main lack I see in
stdlib is NOT having RDoc *automatically* tell the user what files
they need to require() in order to use the module/class/method they
are reading documentation about.

For instance, how is a newcomer supposed to know that they must
require('thread') in order to get the Queue class?  That particular
case is not even intuitive:  if you try require('queue'), Ruby fails
with a LoadError.

In this manner, it would be tremendously helpful if RDoc
*automatically* supplied a "dependencies" or "prerequisites" section
that specifies:  (1) the file you need to require() in order to get
access to the module/class/method, and (2) the fully qualified path
of the module/class that contains the method they are reading
documentation about (if the documentation is about a method).