Core lib clean-up

ruby-talk
1

Looking at the latest ruby-doc.org/core API docs, I suprise how it has
grown since I first started using Ruby. It's gotton kind of disheveled
in there. Perhaps some time should be take to do a full overview of
what in there and determine how it can best be cleaned-up and nicely
organized.

To give an example, take the very first of the "classes" presented, the
Abbrev module. This module containes *one* method, #abbrev. This method
is then called from Array. Why now just make it a method of Array and
be done with it? It the module method is of importance for some reason
(which I seriously doubt) then make it a class method of Array. There's
just no good reason to a have a whole separate module for a single
method.

It would be intersting to hear other's opinions on how the core (and
standard) library could be cleaned-up/improved.

Thanks,
T.

2

Which is a standard library, not a core class. It shouldn't be in those docs at all.

James Edward Gray II

···

On Mar 18, 2006, at 4:38 AM, Trans wrote:

To give an example, take the very first of the "classes" presented, the
Abbrev module.

3

Which is a standard library, not a core class. It shouldn't be in
those docs at all.

Thanks. So there are some issue with the docs themselves. Nonetheless,
in that case, I still don't see why a whole module is used to provide
one method.

T.

4

Trans wrote:

Which is a standard library, not a core class. It shouldn't be in
those docs at all.

Thanks. So there are some issue with the docs themselves.

One being that people have to know whether something is 'core' or 'stdlib' when they look for it.

···

--
James Britt

"Blanket statements are over-rated"

5

I offered my best idea for an improvement to this some time ago on the Ruby Documentation list. Did you not feel building an index page grouped by functionality held any value James?

James Edward Gray II

···

On Mar 18, 2006, at 7:59 PM, James Britt wrote:

Trans wrote:

Which is a standard library, not a core class. It shouldn't be in
those docs at all.

Thanks. So there are some issue with the docs themselves.

One being that people have to know whether something is 'core' or 'stdlib' when they look for it.

6

One being that people have to know whether something is 'core' or
'stdlib' when they look for it.

I take this to mean you thing two shouldn't be listed separately, but
rather together in a single list with, say, an indication next to each
to tell if core or standard? Eg.

  Abbrev (standard)
  Array (core)
  ...

T.

7

James Edward Gray II wrote:

Trans wrote:

Which is a standard library, not a core class. It shouldn't be in
those docs at all.

Thanks. So there are some issue with the docs themselves.

One being that people have to know whether something is 'core' or 'stdlib' when they look for it.

I offered my best idea for an improvement to this some time ago on the Ruby Documentation list. Did you not feel building an index page grouped by functionality held any value James?

Please correct me if my recollection is off, but that would have been a manual process, no? (My apologies if there was a more direct solution and I let it slip off my radar.)

Maintaining doc indices by hand is not really what I would encourage.

(Or else it's Yet Another Task Automation Challenge: parse the core + stdlb index files and merge them to create a master index. Wish I had the time.)

When building Ruby with the " --include-docs" option, all the core & stdlib rdocs should get generated as one set, and ri populated with the full set of data, and the entries annotated to indicate core or not (though the docs themselves really should be clear on what exactly one would need to 'require' to use the code). (On a side note, sort of a shame that docs are not installed by default.)

This may be possible (to some extent) after the installation is complete by running "rdoc --merge" over the full source tree, though the last time I tried that (a few months ago, I think) it quickly raised an error and quit. (My experiment may have lacked rigor; if anyone has specific instructions on how to do this safely, with no risk of screwing my system or site ri files, please let me know.)

···

On Mar 18, 2006, at 7:59 PM, James Britt wrote:

--
James Britt

http://web2.0validator.com - We're the Dot in Web 2.0
http://refreshingcities.org - Design, technology, usability
http://yourelevatorpitch.com - Finding Business Focus
http://www.jamesbritt.com - Playing with Better Toys

8

Well, rdoc has serious problems distinguishing what is core and what
is stdlib... have a look around in the core-docs - everytime a module
is in the stdlib and will be included into a class of the core it
automatically ends up in the core-documentation as well (YAML is
another example for that).
However, rdoc is not able to handle that yet - there was a project
i've been working on (called rdog, one can find it at rubyforge) which
was intended to solve that problem but i never had the time to
continue it :expressionless:
it has a modified version of rdoc that is much more aware of its ties
within the source and knows about superclasses and mixins. Maybe the
rdoc-team could use the changes and do something with them, i really
think rdoc needs some improvements and it has not really been touched
since 2002 afaik...

~~~~manveru

···

On 3/19/06, James Britt <james_b@neurogami.com> wrote:

James Edward Gray II wrote:
> On Mar 18, 2006, at 7:59 PM, James Britt wrote:
>
>> Trans wrote:
>>
>>>> Which is a standard library, not a core class. It shouldn't be in
>>>> those docs at all.
>>>
>>> Thanks. So there are some issue with the docs themselves.
>>
>>
>> One being that people have to know whether something is 'core' or
>> 'stdlib' when they look for it.
>
>
> I offered my best idea for an improvement to this some time ago on the
> Ruby Documentation list. Did you not feel building an index page
> grouped by functionality held any value James?

Please correct me if my recollection is off, but that would have been a
manual process, no? (My apologies if there was a more direct solution
and I let it slip off my radar.)

Maintaining doc indices by hand is not really what I would encourage.

(Or else it's Yet Another Task Automation Challenge: parse the core +
stdlb index files and merge them to create a master index. Wish I had
the time.)

When building Ruby with the " --include-docs" option, all the core &
stdlib rdocs should get generated as one set, and ri populated with the
full set of data, and the entries annotated to indicate core or not
(though the docs themselves really should be clear on what exactly one
would need to 'require' to use the code). (On a side note, sort of a
shame that docs are not installed by default.)

This may be possible (to some extent) after the installation is complete
by running "rdoc --merge" over the full source tree, though the last
time I tried that (a few months ago, I think) it quickly raised an error
and quit. (My experiment may have lacked rigor; if anyone has specific
instructions on how to do this safely, with no risk of screwing my
system or site ri files, please let me know.)

--
James Britt

http://web2.0validator.com - We're the Dot in Web 2.0
http://refreshingcities.org - Design, technology, usability
http://yourelevatorpitch.com - Finding Business Focus
http://www.jamesbritt.com - Playing with Better Toys

9

James Edward Gray II wrote:

Trans wrote:

Which is a standard library, not a core class. It shouldn't be in
those docs at all.

Thanks. So there are some issue with the docs themselves.

One being that people have to know whether something is 'core' or 'stdlib' when they look for it.

I offered my best idea for an improvement to this some time ago on the Ruby Documentation list. Did you not feel building an index page grouped by functionality held any value James?

Please correct me if my recollection is off, but that would have been a manual process, no? (My apologies if there was a more direct solution and I let it slip off my radar.)

True, it was a manual process, but I see the maintenance as quite low and even addressed that in my message. For the curios, here is what I suggested to the ruby-doc list:

I know there are plans to improve documentation searching, but I think a simple layer of links could greatly improve documentation access.

I don't know about others, but I easily look something up in String, Array, and/or Hash grossly more often than anything else. To me that means they should be easy to reach. String is currently the worst:

1. Go to documentation site.
2. Click Core link.
3. Scroll... a lot.
4. Click String link.

We could easily cut that in half, couldn't we? If the front page had some handy categorized links:

Data Structures (or whatever)
Array, Hash, String, Struct

And why stop there? Separation of the standard lib makes little sense here. Change the background color of those links, tag them with an icon, or whatever and there's no reason we can't add those too:

Data Structures
Array, Hash, OpenStruct,
Set, String, Struct

I'm sure I missed a ton. The above is just meant as an example.

So far, I've just been talking about easy access, but this could address other issues. For example, Ruby's reflection is terrificly powerful and maybe the best hid feature of the language! <laughs> There are at least three major classes involved. Quick, name all three without looking... Ah, why bother. Let's just add a group:

Data Structures Reflection
Array, Hash, OpenStruct, Module, Object, ObjectSpace
Set, String, Struct

Again, I'm sure I missed something but you get the idea.

I realize that what I'm suggesting is not easily automated. For that reason, I've tried to come up what the simplest thing that I feel has potential to really ease access. Hopefully, maintaining a single page worth of categorized links would be pretty low maintenance. It only even needs to be checked for new Ruby version releases. (Isn't that yearly?) And I hope String will be safely snuggled in the Data Structures category for a few more releases. :slight_smile:

James Edward Gray II

···

On Mar 18, 2006, at 10:47 PM, James Britt wrote:

On Mar 18, 2006, at 7:59 PM, James Britt wrote:

10

Michael Fellinger wrote:

Well, rdoc has serious problems distinguishing what is core and what
is stdlib... have a look around in the core-docs - everytime a module
is in the stdlib and will be included into a class of the core it
automatically ends up in the core-documentation as well (YAML is
another example for that).
However, rdoc is not able to handle that yet - there was a project
i've been working on (called rdog, one can find it at rubyforge) which
was intended to solve that problem but i never had the time to
continue it :expressionless:
it has a modified version of rdoc that is much more aware of its ties
within the source and knows about superclasses and mixins. Maybe the
rdoc-team could use the changes and do something with them, i really
think rdoc needs some improvements and it has not really been touched
since 2002 afaik...

I looked into using that on Ruby-doc.org; I'm sorry to hear that you don't have infinite free time. :slight_smile:

I should go pull the code again from rubyforge

···

--
James Britt

http://www.ruby-doc.org - Ruby Help & Documentation
Ruby Code & Style - The Journal By & For Rubyists
http://www.rubystuff.com - The Ruby Store for Ruby Stuff
http://www.30secondrule.com - Building Better Tools

11

While we're at it, having gems' rdoc included with ri would be of great
help - especially since many editors can now automatically scan and
display ri info while you code.