[Development] On Removing Public Undocumented/\internal APIs

[David Redondo]

Am Montag, 4. März 2024, 10:57:18 CET schrieb Marc Mutz via Development:
> 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'd like to start a discussion around the expectations of Qt users 
> w.r.t. public (in the C++ sense) API which is either not documented or 
> "documented" as \internal. I put "documented" in quotes because the 
> \internal "documentation" is of course not visible on doc.qt.io.
> 
> First observation: To users, an \internal API is indistinguishable from 
> an undocumented one.
> 
> Well, unless we seriously expect users to verify every result of their 
> IDE's auto completion to be documented, undocumented or \internal in the 
> Qt source code.
> 
> Second observation: Such function _are_ visible in the IDE's auto 
> completion, and in the installed header files, though.
> 
> The question that came up in 6.7 API reviews (repeatedly¹, for some 
> reason (is there some spring-cleaning going on I'm not aware of?) is, 
> then: is it ok to remove such functions? If it's ok to do so, do we need 
> a [ChangeLog][Potentially Source-Incompatible Changes]. And if not, do 
> we deprecate it?
> 
> ¹ Off the top of my head: QString::isSimpleText(), QPen::data_ptr(), 
> QDeferredDeleteEvent
> 
> For reference, when I was still on the other side of the pond (ie. a Qt 
> user), I remember arguing: "well, X is not documented, but it's public, 
> so go ahead and use it", so I'm naturally tending toward classifying 
> such removals as QUIP-6 SiC Type B, ie. unacceptable. Other developers 
> think nothing of it, approving such changes even without an accompanying 
> [ChangeLog].

I can attest to been in the same boat with regards to 1) and 2).
Looking for some needed functionality via autocomplete and the seeing it's not
documented and going with "if it's in the public header then it's fair game".
(Just for reference this was QByteArray::QByteArray(qsizetype size, Qt::Initialization)
 which was \internal before Qt 6.5 and is nowadays public)

David