From: Ken Bloom <kbloom@...>
Date: 2008-03-25T09:09:59+09:00
Subject: Re: Rubybrain.com

On Mon, 24 Mar 2008 11:32:45 -0500, Zoop Zoop wrote:

> I am really confused by rubybrain.com. I like the interface much more
> than the ruby-doc.org documentation, Ajax makes it much more responsive.
> But somehow I could never find what I was searching for and ended up
> looking somewhere else.
> Just some minutes ago I wanted to look up Ruby's String methods... not
> such an unusual task one might think. Searching for the String class led
> me here:
> http://www.rubybrain.com/api/ruby-1.8.6/doc/index.html?
a=C00000226&name=String
> But where are the instance methods?
> The ruby-doc.org docs have them:
> http://www.ruby-doc.org/core/classes/String.html
> 
> Someone please tell me what I do wrong (with the optional hint that I am
> stupid)!

rubybrain.com includes only methods from the standard library (http://
www.ruby-doc.org/stdlib/) which you get by require'ing various files 
outside of the core itself. It does not include the core methods at all. 
It also doesn't tell you which files you need to include to get specific 
instance methods (though you can see this by clicking "show source").

ruby-doc.org suffers from the opposite problem. www.ruby-doc.org/stdlib 
is really nice, letting you know exactly what you need to include, but 
www.ruby-doc.org/core is miserably broken, mixing the core methods and 
the stdlib methods with no way of telling which is which.

noobkit.com gets it right for the core documentation, but works like 
rubybrain.com for the stdlib documentation.

I feel these all miss the features that are truly necessary to use the 
documentation. The underlying schema should be as follows:

+-------------+-----------------------------------------+
| ClassName   |                                         |
| MethodName  | (null if we're talking about a class    |
|             | or a module)                            |
| FileDefined | (or a special marker for core methods)  |
| DocComment  | (the doc comment for this class/method  |
|             | in this file)                           |
| IsModule    | (for class/module definitions only)     |
| SuperClass  | (for class definitions only.            |
|             | Never store "Object" here, because some |
|             | fancy logic is in order to determine    |
|             | whether we're extending the class or    |
|             | defining it for the first time with     |
|             | no ancestor.)                           |
+-------------+-----------------------------------------+

One should be able to filter by ClassName, FileDefined, or MethodName
(and hopefully some predefined groups of files, corresponding to natural
standard library divisions) including several of these criteria 
simultaneously, and get a single documentation page that lays out all of 
the documentation matching the filter.

Anybody got a rails app that does that?

-- 
Ken (Chanoch) Bloom. PhD candidate. Linguistic Cognition Laboratory.
Department of Computer Science. Illinois Institute of Technology.
http://www.iit.edu/~kbloom1/