[Development] On Removing Public Undocumented/\internal APIs

[Fabian Kosmale]

Hi,

as one of the people complaining to Marc on the change:

I really don't like "undocumented API can change", especially not for 
members. Using such a member is one tab completion away

I'm willing to make some amends (function which can't be used without 
also using private API, like a function taking an instance of a private 
class), but I think the general guide line should IMHO be: Use the 
normal deprecation workflow for them.

To respond to Volker's point
 > 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

Well, there's Hyrum's law. And I'm guilty of breaking user code by 
changing the  semantics of under-specified code myself, but I'd still 
argue that we should avoid that as much as possible.

Lastly, I'd push against putting undocumeted/internal functions into 
public headers to begin with to reduce that friction in the future. Or 
if we end up with a more nuanced stance like "function which can't be 
used without also using private API", consistently use the "Badge 
pattern" [1] for them, to make it impossible for anyone to use them 
outsider of their intended context.

Kind regards,
Fabian

[1] https://awesomekling.github.io/Serenity-C++-patterns-The-Badge/

On 10.07.25 14:37, Marc Mutz via Development wrote:
> Hi,
> 
> I'm coming back to this thread, because this conclusion:
> 
> 
> Confidential
> On 18.03.24 16:28, Volker Hilsheimer wrote:
> [...]
>>
>> to use those APIs you have to read the code. And
>> then you’ll see that they are either undocumented, or documented as
>> \internal.
>>
>> You can still use them, but you know that they might change.
> [...]
> 
> is being challenged for a recent change of mine that renamed
> undocumented QArrayData::ref_ to m_ref¹. There's a growing pile of reviewers
> that don't like the change, mainly because it breaks QtC (a fix is
> available already², there's also a revert³ of the original change)
> 
> ¹ https://codereview.qt-project.org/c/qt/qtbase/+/651494
> ² https://codereview.qt-project.org/c/qt-creator/qt-creator/+/660083
> ³ https://codereview.qt-project.org/c/qt/qtbase/+/660072
> 
> With the above rule, undocumented is equivalent to private. In particular,
> you have to assume that undocumented API changes at any time.
> 
> We now see how loud the outcry is when such changes, routinely done
> every week, happen to hit one of our own tools with a vocal developer base.
> 
> Do we still uphold the rule? I will bow to the decision, but either the
> change is allowed alongside all others, or none are. It can't be that
> we apply double standards.
> 
> Thanks,
> Marc
> 
> --
> Marc Mutz <marc.mutz at qt.io> (he/his)
> Principal Software Engineer
> 
> The Qt Company
> Erich-Thilo-Str. 10 12489
> Berlin, Germany
> www.qt.io
> 
> Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
> Sitz der Gesellschaft: Berlin,
> Registergericht: Amtsgericht Charlottenburg,
> HRB 144331 B
> 

-- 
Fabian Kosmale
Manager R&D

The Qt Company GmbH
Erich-Thilo-Str. 10
D-12489 Berlin
fabian.kosmale at qt.io
+49 1638686070