I've been doing some Sunday reading:
Interface-Oriented Design
Ken Pugh
Pragmatic Bookshelf, 2006, ISBN 0-9766940-5-0
In the process, I started thinking about ways that ri
could be improved. Here are some Partly-Baked Ideas.
Disambiguation
If ri is asked about a string (such as "to_i") that appears
in multiple method names, it simply lists the matches:
More than one method matched your request. You can refine
your search by asking for information on one of:
Float#to_i, Float#to_int, Integer#to_i, Integer#to_int,
IO#to_i, ..., Zlib::GzipFile#to_io
I see two problems with this approach. First, all of the
results are jumbled together. Second, very little information
is given about the individual results. How about:
More than one method matched your request. You can refine
your search by asking for information on one of:
...#to_i - returns an integer representation
Float#to_i (same as Float#to_int)
Returns _flt_ truncated to an +Integer+.
Integer#to_i (same as Integer#to_int)
As _int_ is already an +Integer+, simply return
the receiver.
...
...#to_io
...
To be sure, there are some implementation difficulties with
this idea. Specifically:
* Some information will need to be gathered:
- "generic" descriptions, such as "returns an integer
representation".
- "same as" information for methods
- "stand-alone" descriptions that don't rely (much) on
context from a full ri response.
* There is the possibility of multiple, clashing generic
descriptions (e.g., method "foo" does really different
things in different classes). Then again, this could
indicate something to address in the naming...
Context
Unix man pages have "SEE ALSO" sections that list other,
closely-related man pages. Something like this might be
useful in ri.
It might also be useful to display a "family tree" that
shows where the same method shows up in related classes.
-r
--
http://www.cfcl.com/rdm Rich Morin
http://www.cfcl.com/rdm/resume rdm@xxxxxxxx
http://www.cfcl.com/rdm/weblog +1 650-873-7841
Technical editing and writing, programming, and web development
|
