[Development] On Removing Public Undocumented/\internal APIs

[Volker Hilsheimer]

> On 4 Mar 2024, at 10:57, Marc Mutz via Development <development at 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