From: James Britt Date: 2008-03-17T01:47:35+09:00 Subject: Re: argh! more undocumented mysteries: to_yaml Stefano Crocco wrote: > > How are you supposed to know that to_yaml is not in ruby core but in the > standard library? I don't really know. Yes; it is a good question. Sadly, the rdoc/ri tool is brain-dead about mix-ins. When I started using ruby some years > ago, I downloaded a version of the rdoc documentation from > www.ruby-doc.org which only included documentation for the core classes (that > is, those you can use without need to require some files), while documentation > for the standard library was in a separate package. Unfortunately, the > documentation you can find nowadays includes both core and standard library. It appears that the Ruby source code includes .document files that direct which source files should be processed by rdoc What has happened is that there is no clear separation in the rdoc settings between core classes and standard lib. The Yaml source files get pulled in by rdoc along with several other std-lib files, as well as core files. Rdoc stores what it finds and emits an aggregate result. Since yaml alters core classes, the resulting rdoc falsely shows Array, String, etc as having to_yaml methods as if they were built into the original code. There is no indication that those methods only exist if YAML is included. > This has the very unpleasant side effect of displaying together methods which > come from the core classes and methods which come from files in the standard > library (which should be required before using such methods). At any rate, at > the top of the page, just below the name of the class, there's a list of the > files which have been used to generate the documentation for the class. If a > method listed in the documentation doesn't seem to exist, try requiring those > files. A useful tip, but a sad indication of rdoc's failings with mix-ins. -- James Britt "Inside every large system there's a small system trying to get out". - Chet Hendrickson