> On 4 Mar 2024, at 10:57, Marc Mutz via Development 
> <development@qt-project.org> wrote:
> 
> Hi,
> 
> TL;DR:
> - Treat all APIs not clearly marked as private (private access, *Private
>   namespace or "We mean it!" comment) as public, in particular keep SC/BC
>   and deprecate before remove.
> - Avoid adding APIs that aren't clearly private or public in the future.

[…]

> I would suggest that we treat any entity defined in a header file that 
> is not in a *Private namespace or under the umbrella of an "We mean it!" 
> commant, in short: anything that isn't _visible_ as non-public API _from 
> the header file_, as semi-public, and apply the same rules as for public 
> API: keep BC/SC, deprecate first, remove second, and adjust QUIP-6 
> accordingly.

I think we have to acknowledge that Qt is 30 years old this year, and over the 
decades the capabilities of tools, the features of the languages, and the best 
practices, skills, and awareness of the people working on Qt have changed a 
lot. What usually hasn’t changed is the *intent* of the class author - even 
though it might be buried deep in the historical repositories. Stating now that 
everything that has the technical appearance of a public API cannot be changed, 
and ignoring the author’s intent, does not seem constructive.


> ¹ Off the top of my head: QString::isSimpleText(), QPen::data_ptr(), 
> QDeferredDeleteEvent

Undocumented APIs in any SDK are, IMHO, “use at your own risk”. I (or my IDE) 
might find something promising in some public header, but if I have no 
information about what the author of that thing is promising me, should I use 
it in my code? Sometimes it’s more obvious than other times, but what on earth 
is the semantics of "QString::isSimpleText”? What is that “DataPtr” reference 
returned by "QPen::data_ptr”? Can anyone use QDeferredDeleteEvent::loopLevel() 
in a meaningful way without studying the event delivery code?

> At the same time, we should make sure that we don't accept such 
> semi-public APIs going forward anymore.

I do agree that we shouldn’t add more such stuff, at least not without making 
it visible in the header, ideally in a way that makes it visible to code 
completion (if that’s possible at all).

For stuff that is there today (e.g. various container types’ “isSharedWith” 
public member function, usually documented explicitly as \internal, and often 
used in other modules or in tests so not really practical to do it any other 
way), should we add a "// internal” comment in the header file?

Cheers,
Volker


-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Reply via email to