[Development] api changes

[Thiago Macieira]

On sexta-feira, 13 de abril de 2012 11.03.58, Girish Ramakrishnan wrote:
> Hi Thiago,
> > Let's please not invent a new rule.
> > 
> > If it's _p.h, it's private, otherwise it's public and subject to source-
> > and binary-compatibility guarantees. If there's API in some files that we
> > don't want to keep BC on, let's move them to a _p.h file.
> > 
> > Plugins can include those since we do install private headers in Qt 5.
> > 
> > Also, syncqt will not generate forwarding headers for classes in the _p.h
> > files. This helps us by not including one of them by accident by #include
> > <QtGui/QPlatformWhatever>.
> 
> All platform plugins, unfortunately, do exactly this. Fixing them all
> though entirely possible though. There's also some inconsistency with
> some of the qpa files being named _qpa_p.h :-)
> 
> How about we fix this properly for 5.1? And for the moment, also have
> the understanding that _qpa.h is internal?

Immediate action then:

1) make sure all such classes are documented \internal, so they don't show up 
in docs

2) add #pragma qt_no_master_include so that they aren't included in <QtGui> 
and people use them by accident because they happened to complete in QtCreator 
or another IDE

3) no _qpa.h includes in public headers

4) no includes of _qpa.h forwarding headers in public headers either

Later:

5) add #pragma qt_sync_stop_processing so that the forwarding headers aren't 
added, fixing the code that used them

6) rename _qpa.h to _p.h and update all includes to have private/xxx_p.h 
(there's no need to have "qpa" in the name, since QPA is the only platform -- 
it's implied)

At any time:

7) create proper public API where needed

Personally, I'd invert the order of 4 and 5: if you do 5 before 4, 5's actions 
will make it clear where 4 needs to be fixed. So, by doing 5, you do 4 more 
easily.

> >> > 3. _qpa.h files are installed only so that we can allow development of
> >> > plugins outside of qt source. I would like to see them not getting
> >> > installed at all but I don't know if this is an oversight or
> >> > intentional.
> > 
> > All headers are installed. This rule is unnecessary.
> 
> Right, but only if we change all _qpa.h to _qpa_p.h. Correct?

All headers are installed, whatever their names.

The difference is whether they are inside private/ or not. As an effect of step 
6 above, they move into private/, which makes their accidental use impossible. 
If we can't do that step before 5.0, then we need to tell people that they 
shouldn't include those headers.

I really, really, REALLY recommend we do that step before 5.0. What will we 
look like if we start adding 5.0 errata over 2 months before the release?

> >> The handle() that gets the QPlatformWindow etc? Yeah, I guess those
> >> serve no great purpose in the public API.
> > 
> > Just say that the type of the pointer returned by such functions is not
> > part of Qt's public API. Private Qt API and non-Qt API fall under that
> > definition.
> You are suggesting that this be a documentation fix instead of an API
> fix? I think I like that because I tried removing some of the handle()
> and found that plugin code uses it. Compile fails since the plugins
> are not friends. I will just mark them all as \internal.

Yes, it's a documentation fix.

Matched, of course, by the pointers being either opaque (Qt private) or defined 
in a non-Qt header.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center
     Intel Sweden AB - Registration Number: 556189-6027
     Knarrarnäsgatan 15, 164 40 Kista, Stockholm, Sweden
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120413/1faf21b8/attachment.sig>