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
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
