"Charles Hixson" <charleshixsn / earthlink.net> schrieb im Newsbeitrag news:4174203E.7010704 / earthlink.net... > 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.) That's a really nice class! ;-) I totally agree with you: unfortunately most developers have a much stronger focus on getting the code right and working bug free than on documentation. I know, often it's time pressure imposed by project deadlines or whatever. But with open source that should be different. And a crucial part of writing a library is getting the docs right. A lib without proper doc will simply be ignored - and I guess nobody does write code for the waste bin. Personally I trie to document as I write, because it's much faster than digging into the code later and it also helps me, if I have to go back there after some time. After all, I have to maintain code and find bugs - so I appreciate comments very much. Also, with Eclipse writing Javadoc is just sooo simple. Kind regards robert