function v. method

[Gerhard Fiedler]

On 2006-07-24 13:25:14, fuzzylollipop wrote:

>> So... the final authority /is/ the code. I don't see an alternative. For
>> me, good abstraction doesn't mean I don't have to read the sources; good
>> abstraction means (among other things) that I can read the sources easily.

> having auto generated docs, which means the documentatin is in the code
> as doc strings, javadoc, reflex, or whatever format is the BEST way of
> doing API documentation, period.

It may be the best way, no contest to that. But it still is not the code.
(I actually think that possibly the current way of embedding javadoc-like
documentation into sources is only a stepping stone into the direction
generally pointed to by what Wirth called "literate programming". In any
case, I'd rather not call it the "best way, period"; calling it the "best
currently widely supported way" seems more appropriate to me.)

Even doc strings tend to get out of sync with the code. And even doc
strings document (at best) what the code should do, not what it actually
does. And even doc strings are not always complete in describing the
functionality.

So auto generated docs are also incomplete and out of sync with the code,
sometimes more, sometimes less, sometimes so little that it is not
relevant. But you can't know how much out of sync they are from reading the
docs alone. So when push comes to shove (or so the saying goes? :), the
code is the authority. Even with auto generated docs. Period... ?!? <g>

Gerhard