This post originated from an RSS feed registered with Ruby Buzz
by James Britt.
Original Post: API docs on Ruby-doc.org have been updated
Feed Title: James Britt: Ruby Development
Feed URL: http://feeds.feedburner.com/JamesBritt-Home
Feed Description: James Britt: Playing with better toys
I just updated Ruby-doc.org with the current set of Ruby API docs. Yeah, I know what you’re thinking: “Wow, James, that was fast!”
Actually, I let things slip way too long. I’ve a million really good reasons, but I can’t imagine anyone wants to hear them. However, a few things to note:
The site now defaults to showing the core and standard-lib docs for Ruby 1.9.2. There are additional links to core and standard-lib docs for 1.8.7 and 1.8.6. I expect that the new default version will disturb some people. I had earlier changed the default to 1.8.7, and there was much noise, because while it was arguably the current Ruby 1.8, it was by no means commonly used. And at that time 1.9 has not gained much adoption. I think the situation is better now. Making either 1.9.7 or 1.9 the default would be a sensible choice. I picked 1.9, though, because that’s where it’s all headed anyway. (One thing that occurred to me as I was checking the new links, though, is that the doc pages do not tell you the Ruby version. I need to go see how I can best set that in the rdoc template someplace to reduce confusion.)
The site is still using RDoc. I’d like to change that, but for expediency I decided to just bite the bullet and get it done and get some fresh files up. One major annoyance with RDoc is how it handles the processing of code that modifies other objects. RDoc collects all the doc items for all the classes, modules, etc., it encounters and emits them without distinction of source. For example, if you run rdoc over the entire Ruby source directory, it will read in the source files for String, Array, and other core classes, but also the code for YAML. YAML defines additional methods on core classes; the resulting API files will end up showing String as having a to_yaml method. But this is only true when you explicitly include the YAML module, and the docs do not make that at all clear.
To avoid this confusion rdoc needs to be run in segments, first covering only the core code, and then each of the standard libraries. Covering just the core is not a big deal, but running rdoc over the right sub-section of files for each of the standard libraries is more involved.
Gavin Sinclair wrote a tool, stdlib-doc, to manag this. It uses a few configuration files to not just define what files constitute what library, but also mixes in a status report and other information. It’s terrific but, as you might imagine, it requires steady maintenance. Since there is no automagic means to determine just how well doc’ed a library may be, some human has to keep stay involved and look progress updates. That simply hasn’t happened for some time now. Also, I think the list of standard library files differs among the different versions of Ruby, so each version needs its own set of metadata file. I’ve just used the one for ruby 1.8.6.
The upshot is that the status reports and such for each of the stdlib pages are wrong. I need to clean up, or remove, those pages (including links for doc tarball downloads). I started making some changes as I was adjusting templates and code, but decided that we would all be better off if I first just got new doc pages up before getting caught up in other tasks.
I want to thank the people who wrote to me and asked about getting the site updated; it helped motivate me to get a plan together and put it into action.
Big thanks of course go to the people who put in the time and effort to write docs. It is largely a thankless task; no one says squat about docs unless they are missing or crappy. That’s wrong; these people deserve your appreciation, so let them know.
Next steps: fix up the stdlib meta-pages; review using Yard or Ruby 1.9.2 RDoc for doc generation; change the templates to play nice on mobile devices; drop or improve the use of frames; add user comments/discussion.
Yard is quite impressive, but the last time I ran it over the Ruby sources I was bothered by the volume of error and warning messages. What first caught my eye about Yard was that is offered meaningful URLs (that is, the links to methods were not identified with “M0444” or something arbitrary like that, but the actual method name). It turns out that the current Ruby rdoc does this as well. I much prefer the template system in Yard, but the errors/warnings (and in some cases, actual process failure) are an issue. But, as it happens, I’ve been having similar issues running the current rdoc over some of the source code. (And I hate the default Darkfish template.)
If all goes well it won’t take me until next New Year’s Day to make some more progress.
Previous Topic
