From: Hugh Sasse <hgs@...>
Date: 2006-08-03T01:02:09+09:00
Subject: Re: doc patch: weakref.

On Thu, 3 Aug 2006, mathew wrote:

> 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.

OK, you've convinced me that this leads to broken encapsulation.
I'll look at this further.  It is probably best ensure the contract
is specified by unit tests though, but the creation of a complete
test set has been another topic recently, so I'll say no more here..

        Thank you
        Hugh