Looking at the latest RDoc Documentation 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.
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.
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.
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?
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…
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.)
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.
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:
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.
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.
