API robustness - (was: Different ways to create a directory)

[Allen Winter]

On Saturday 08 August 2009 11:07:36 pm you wrote:
> Hi,
> 
> > > Aren't they just duplicating functionality available elsewhere?
> > 
> > I don't think so.
> > 
> 
> This is something (and this very case) that I lovingly criticize about our own 
> API and in general the way people can use our API (and Qt's API).
> 
> Sometimes (even on our own code) we mix up QFile & its features with for 
> instance, KIO, or NetAccess (what is KIO also in the end).
> 
> I actually think this can confuse developers, and in some way one sometimes 
> can be tempted to use Qt's API sometimes where KDE's is strongly suggested.
> 
> In this special case I think we should only advise (from my POV obviously) KIO 
> and NetAccess usage. Also, they should have some kind of flag to create all 
> the missing folders to complete the path. This way, yet another symbol is not 
> needed.
> 
> So apart from the general rule that if you have KFoo and QFoo, use KFoo, we 
> should have some kind of flag for the documentation called something like 
> "@replaces". Like in KIO::mkdir, "@replaces QDir::mkdir". Basically, because 
> KIO will _always_ do the right thing, while you can expect failures when QDir 
> is given non local URI's.
> 
> What I am talking about is API robustness and intuitiveness.
> 
Certainly I won't argue against better documentation, robustness and intuitiveness.

I will add any doxygen tags we want. No problem.
But I don't see that we need that. We just need people to add such recommendations
to the existing documentation.