[Development] No implementation hints in Qt Documentation

[Olivier Goffart]

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.