"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