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.)