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. -- http://mail.python.org/mailman/listinfo/python-list
