function v. method

[fuzzylollipop]

Gerhard Fiedler wrote:
> On 2006-07-22 16:32:38, danielx wrote:
>
> >>>> ...and source code...
> >>>
> >>> *shudders* What happened to all the goodness of abstraction?
> >>
> >> Abstraction as you seem to use it requires complete docs of the interface.
> >> Which is what you said you don't have... So the original abstractor broke
> >> the abstraction when publishing insufficient docs, not the one who looks
> >> into the sources to find out what actually happens.
> >
> > Absolutely. I didn't mean the user was breaking abstraction (let's not
> > blame the victim). I was saying that we should really have more
> > sympathy for him.
>
> I have all the sympathy in the world for him... after all, he's me :)
>
> But one reason why I try to write (and insist on as much as possible from
> people writing for or with me) self-documenting code is that wherever you
> have documentation and code separated (which is the case of API docs), you
> can bet (without losing) that sooner or later code and doc will diverge.
> This has a probability that approaches 1 :)
>
> So, I agree with you that good API docs are a good thing, as they tell me
> everything I need to know without having to wade through tons of
> implementation details that may be interesting but don't serve my immediate
> need (of having to use the API). But reality seems to be (and mine so far
> definitely is) that these docs, even the good ones, are not completely in
> alignment with the reality of the code. (We all know that code has bugs...
> and the API always describes, at best, how the code /should/ work. It never
> describes how it actually works, including the bugs <g> (this
> notwithstanding the bugs that have been elevated to features and henceforth
> been described in the API docs).
>
> 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.
>
> Gerhard

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.