This may have been brought up before, but as a newbie Ruby programmer,
I've just been tripped up by an error in the documentation at ruby-doc.org.
I've only just heard that this documentation is years out of date and
well-known to be inaccurate. I had no idea that this was the case and
learned the hard and time-consuming way.
If this is case, it's going to be tripping up other (new) users,
especially as it's listed first on http://www.ruby-lang.org/en/documentation/. Perhaps a warning to this
effect, or a complete removal of the link would be justified, together
with the promotion of rubydoc.info?
I've found the 1.9 documentation on the site to be pretty OK. I don't
think I agree that it's "years out of date."
Can you share the example that tripped you up?
If we need to get the documentation site updated, I would prefer we
email those maintainers and push them to do so instead of giving up on
that resource.
James Edward Gray II
···
On Sun, Sep 11, 2011 at 9:24 AM, Matthew -- <astrochase@gmail.com> wrote:
This may have been brought up before, but as a newbie Ruby programmer,
I've just been tripped up by an error in the documentation at
ruby-doc.org.
I've only just heard that this documentation is years out of date and
well-known to be inaccurate.
This may have been brought up before, but as a newbie Ruby programmer,
I've just been tripped up by an error in the documentation at
ruby-doc.org.
I've only just heard that this documentation is years out of date and
well-known to be inaccurate.
I've found the 1.9 documentation on the site to be pretty OK. I don't
think I agree that it's "years out of date."
Can you share the example that tripped you up?
If we need to get the documentation site updated, I would prefer we
email those maintainers and push them to do so instead of giving up on
that resource.
It confuses me how this can be wrong, especially as I'm under the
impression it's generated straight from the source code.
I don't have enough experience to judge how accurate ruby-doc.org is.
Perhaps someone with more experience than I can comment, but if it is
plagued with problems as I've been hearing, perhaps a warning should be
placed next to the link on the main Ruby website, at least until the
problems are resolved.
···
On Sun, Sep 11, 2011 at 9:24 AM, Matthew -- <astrochase@gmail.com> > wrote:
Yeah, Ruby's primary documentation tool just doesn't show overrides as
you suggest. That probably would be handy, but it could also be
pretty tough to accomplish with how dynamic Ruby can be.
Anyway, if we're going to consider changes like that, they probably
need to happen inside RDoc. I don't think this is really and issue
with our sites so much as our tools.
James Edward Gray II
···
On Sun, Sep 11, 2011 at 10:14 AM, Matthew -- <astrochase@gmail.com> wrote:
It confuses me how this can be wrong, especially as I'm under the
impression it's generated straight from the source code.
I don't have enough experience to judge how accurate ruby-doc.org is.
Perhaps someone with more experience than I can comment, but if it is
plagued with problems as I've been hearing, perhaps a warning should be
placed next to the link on the main Ruby website, at least until the
problems are resolved.
Yeah, Ruby's primary documentation tool just doesn't show overrides as
you suggest. That probably would be handy, but it could also be
pretty tough to accomplish with how dynamic Ruby can be.
How does rubydoc.info achieve it? I'm really unclear as to what's gone
wrong with ruby-doc.org if other sources of documentation (that I didn't
know about this morning) are correct. The ri tool is also correct.
Not showing overriden methods is a pretty substantial problem! That
means the documentation will be wrong and misleading end to end.
In the example I found, File.open has a completely different interface
to IO.open. That's a pretty big deal. The only reason I picked up
something was wrong was because I'd just read the pickax book and
couldn't find the matching documentation. This threw me off and I've
lost confidence in that documentation all together. The trouble is, I
made the (reasonable) presumption that the documentation wouldn't
mislead me!
If I've succumb to this, there's got to be other people that have too.
IHMO, this limitation needs to be noted so that other people don't fall
into this trap too.
While we're at it, I'll mention something annoying me to no end for
some time now: ruby-doc.org's stdlib documentation is missing for some
libs. Go to http://ruby-doc.org/stdlib/ and start clicking links on
the left - soon enough you'll find some what return a 404. For
example, Win32API, soap, readbytes, and I haven't even checked a third
of the list.
If the docs for these are actually missing, then you should show some
user-friendly messages or at least a list of methods, like rubydoc.info does.
While we're at it, I'll mention something annoying me to no end for
some time now: ruby-doc.org's stdlib documentation is missing for some
libs. Go to RDoc Documentation and start clicking links on
the left - soon enough you'll find some what return a 404. For
example, Win32API, soap, readbytes, and I haven't even checked a third
of the list.
If the docs for these are actually missing, then you should show some
user-friendly messages or at least a list of methods, like
rubydoc.info does.
Towards the end of last month I uploaded some updated documentation to a free Heroku instance:
Note: this is a free Heroku instance so it will be pretty flakey. However all the files served are static so it won't be too bad hopefully.
When contacting the ruby-doc.org maintainer about having it hosted for the time being, he stated that there were going to be updates at some point. He also stated that there are issues with the way that RDoc does some of the processing of class hierarchy, so a custom tool is used. I've requested more information but haven't heard anything back yet. At any rate, the URL above uses an updated rdoc with the darkfish template. On a side note I'm trying to put together a Ruby Language Guide. In essence I'd like to make it something more organized. The problem with the current state of documentation from a reference perspective is that it lacks an organized structure. Take for example the Array class. Arrays have methods for obtaining values, modifying values, and iterating over values. This sort of categorization is simply too difficult to automate given the current state of things, and would require linking to some kind of external metadata.
Also the inline documentation samples are very concise (part of which is to not create walls of comments in the code) and are often written in a "here's the input and here's the output" style. There are some cases to where showing usage more tailed towards real world use requires much more detailed code.