Asp Forum - Core lib clean-up

Trans

3/18/2006 10:35:00 AM

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.

9 Answers

James Gray

3/18/2006 4:48:00 PM

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.

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

James Edward Gray II

Trans

3/18/2006 8:26:00 PM

> 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.

james_b

3/19/2006 1:59:00 AM

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"

Trans

3/19/2006 3:14:00 AM

> 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.

james_b

3/19/2006 4:48:00 AM

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.0val... - We're the Dot in Web 2.0
http://refreshing... - Design, technology, usability
http://yourelevato... - Finding Business Focus
http://www.jame... - Playing with Better Toys

Michael Fellinger

3/19/2006 7:21:00 AM

Well, rdoc has serious problems distinguishing what is core and whatis stdlib... have a look around in the core-docs - everytime a moduleis in the stdlib and will be included into a class of the core itautomatically ends up in the core-documentation as well (YAML isanother example for that).However, rdoc is not able to handle that yet - there was a projecti've been working on (called rdog, one can find it at rubyforge) whichwas intended to solve that problem but i never had the time tocontinue it :|it has a modified version of rdoc that is much more aware of its tieswithin the source and knows about superclasses and mixins. Maybe therdoc-team could use the changes and do something with them, i reallythink rdoc needs some improvements and it has not really been touchedsince 2002 afaik...~~~~manveruOn 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.0val... - We're the Dot in Web 2.0> http://refreshing... - Design, technology, usability> http://yourelevato... - Finding Business Focus> http://www.jame... - Playing with Better Toys>>

james_b

3/19/2006 2:31:00 PM

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 :|
> 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. :)

I should go pull the code again from rubyforge

--
James Britt

http://www.ru... - Ruby Help & Documentation
http://www.artima.c... - The Journal By & For Rubyists
http://www.rub... - The Ruby Store for Ruby Stuff
http://www.30seco... - Building Better Tools

eastcoastcoder

3/19/2006 3:07:00 PM

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.

James Gray

3/19/2006 4:08:00 PM

On Mar 18, 2006, at 10:47 PM, James Britt 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.)

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. :)

James Edward Gray II

comp.lang.ruby

Core lib clean-up

Trans

James Gray

Trans

james_b

Trans

james_b

Michael Fellinger

james_b

eastcoastcoder

James Gray

x Login to ForumsZone