Robert Klemme wrote: >"Charles Hixson" <charleshixsn / earthlink.net> schrieb im Newsbeitrag >news:4172C21A.4050407 / earthlink.net... > > >>Robert Klemme wrote: >> >> >> >>>I always use the online doc at rubydoc.org. Look for documentation of >>>classes Class and Module. >>> robert >>> >>> >>There's documentation there, allright, but the methods seem to be a bit >>shy of definition... >>I can't even tell if any of the databases will accept integer values >>rather than string, much less object. And many of the methods don't >>give any indication as to what the various parameters are supposed to >>look like method(p1, p2) isn't very explicit. (I forget which method >>that was. I was just checking out the site after your recommendation.) >> >>That said, SOME of the methods seem reasonably, or even well, >>documented. Presumably this is an ongoing project, but for now it's not >>really suitable as a primary reference. Example code is needed to fill >>in the gaps. Methods that don't occur in the examples are likely to >>require digging into the source. >> >> > >.... or resort to some other form of doc, maybe Pickaxe II. > > Pickaxe II has the same problem. In fact, they explicitly acknowledge the problem towards the start of the book. Something about adding proper documentation would have doubled the length of the book. (I don't have it right to hand at the moment.) Their comment is that one should use the on-line documentation, which has been improving rapidly, but not as fast as the class libraries have been growing. A part of the problem is that in a non-typed language just knowing how many parameters there are doesn't tell one as much as it does in a typed language. In C at least the automatic documentation can tell you whether it's an integer or a string that's expected. Still, that's only a small part of the problem, I've seen C documentation that's just as bad or worse. The problem is that to effectively use a method you need to know what how the parameters are interpreted, and no automatic documentation system can do more than help with that. Even Eiffel, which has some of the best automated documentation that I've seen, and is strongly typed to boot, runs into that problem. Ideally the programmer would document the code as he wrote it. (I know how hard that is, but it does produce the best results.) A secondary possibility is that someone else could go back through the code and annotate it. This works, but takes longer, albeit the time isn't all spent by the same person, and it can be done while debugging. Still, that will never provide complete coverage. >I find this doc quite comprehensive: >http://www.ruby-doc.org/core/classes/Module.html#M000695 >http://www.ruby-doc.org/core/classes/UnboundMethod.html > >Although I'd readily admit that the path from Class to Module is not very >apparent since the line "Parent Module" is quite small and can be easily >overseen. > >Btw, I use the Ruby Sidebar which is quite useful: >http://www.ruby-doc.org/docbar/toc_tut.html > >Kind regards > > robert > And I agree with you. Those two were quite well documented. (Well, I didn't actually READ the documentation, just looked it over.) But for many of the methods (not THOSE methods, but look, e.g., at EOFError) it seems to be a bare list of methods & parameters, depending on the names chosen for the parameters to carry the meaning. As if rdoc had been run on uncommented code. (Which I know well, because my code usually starts out that way.) Still, the place I normally end up looking is in the standard library, where I find things like <a href="http://www.ruby-doc.org/stdlib/libdoc/sdbm/rdoc/index.html">sdbm</a>. NowI know that that is automatically generated, but that happened to be the part I needed. (Past tense. I gave up and did things a different way. But I still don't know if I *COULD* have used sdbm. I suspect not, but I don't KNOW.)