From: mathew <meta@...>
Date: 2006-08-03T00:37:03+09:00
Subject: Re: doc patch: weakref.

Hugh Sasse wrote:
> Not sure that's such a problem: the interface is unlikely to change
> once established, and helping people understand how parts of the 
> standard library work is the point of docs.  But I don't feel strongly 
> about this.  It could be argued this violates DRY also, though.
>   

I strongly disagree. The purpose of library API documentation is to act 
as a design contract, specifying the behavior of the library call, and 
not specifying anything which the user should not rely on or does not 
absolutely need to know.

Implementation details should not be mentioned in the API, because if 
they are, people will write code that relies on them, and we will then 
be unable to refactor the code later without breaking lots of software.

This is also the problem with undocumented library calls--with no 
documentation, people have to try and guess the contracted API based on 
the code. If they guess wrong, their code breaks when we need to 
refactor. And we end up with untouchable nightmare code, like the CSV 
parsing library (see previous discussions).


mathew