Forum: Ruby Core lib clean-up

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
45196398e9685000d195ec626d477f0e?d=identicon&s=25 Trans (Guest)
on 2006-03-18 11:39
(Received via mailing list)
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.
4299e35bacef054df40583da2d51edea?d=identicon&s=25 James Gray (bbazzarrakk)
on 2006-03-18 17:49
(Received via mailing list)
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
45196398e9685000d195ec626d477f0e?d=identicon&s=25 Trans (Guest)
on 2006-03-18 21:30
(Received via mailing list)
> 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.
Bc6d88907ce09158581fbb9b469a35a3?d=identicon&s=25 James Britt (Guest)
on 2006-03-19 03:00
(Received via mailing list)
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"
4299e35bacef054df40583da2d51edea?d=identicon&s=25 James Gray (bbazzarrakk)
on 2006-03-19 04:18
(Received via mailing list)
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?

James Edward Gray II
45196398e9685000d195ec626d477f0e?d=identicon&s=25 Trans (Guest)
on 2006-03-19 04:21
(Received via mailing list)
> 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.
Bc6d88907ce09158581fbb9b469a35a3?d=identicon&s=25 James Britt (Guest)
on 2006-03-19 07:29
(Received via mailing list)
James Edward Gray II wrote:
>> 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
86e33dee4a89a8879a26487051c216a8?d=identicon&s=25 Michael Fellinger (Guest)
on 2006-03-19 12:17
(Received via mailing list)
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...

~~~~manveru
Bc6d88907ce09158581fbb9b469a35a3?d=identicon&s=25 James Britt (Guest)
on 2006-03-19 15:31
(Received via mailing list)
Michael Fellinger wrote:
> 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.ruby-doc.org       - Ruby Help & Documentation
http://www.artima.com/rubycs/ - The Journal By & For Rubyists
http://www.rubystuff.com      - The Ruby Store for Ruby Stuff
http://www.30secondrule.com   - Building Better Tools
F3b786a23390451fa67108781b0c8fed?d=identicon&s=25 unknown (Guest)
on 2006-03-19 16:08
(Received via mailing list)
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.
4299e35bacef054df40583da2d51edea?d=identicon&s=25 James Gray (bbazzarrakk)
on 2006-03-19 17:07
(Received via mailing list)
On Mar 18, 2006, at 10:47 PM, James Britt wrote:

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

> 2.  Click Core link.
> sense here.  Change the background color of those links, tag them
> address other issues.  For example, Ruby's reflection is terrificly
> 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
This topic is locked and can not be replied to.