[Development] No implementation hints in Qt Documentation

Olivier Goffart olivier at woboq.com
Thu May 3 22:54:38 CEST 2012

On Thursday 03 May 2012 12:30:21 Thiago Macieira wrote:
> In any case, the documentation is what's valid. If the code and the
> documentation differ, usually the documentation prevails and the code needs
> to be changed.

I think this is an overstatement.
If there is conflict between the documentation and the implementation, I 
rather change the documentation. Unless it is clearly a bug.

Rationale: Changing the behaviour of something might break existing 
application (remember we pretend to maintain binary compatibility).
While a change to the documentation won't break anyone's code.

> I'm not saying the documentation will always be enough. But it should be
> good enough for the vast majority of the cases, 

It should.  But that implies the documentation is pefrectly written.

> so looking into the source
> code should not be necessary. At least, not while you're writing your own
> code 

I like to know what is under the hood when i am writing my own code. It helps 
to understand the performence penalty, and also the corenr case.
For example, we don't document the complexity of every function.

More information about the Development mailing list