[Development] api changes

[Girish Ramakrishnan]

Hi Thiago,

2012/4/13 Thiago Macieira <thiago.macieira at intel.com>:
> 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)
>

Yes, agreed (and thanks for those pragmas that I was not aware of).

I think the idea with _qpa_ in the file name is to imply that it has
plugin api. As opposed to let's say qpen_p.h. This means that when I
see a change to a _qpa.h file, I know that plugins will get affected
by this api change. However, this fact can already be deduced from the
qplatform prefix. The only exceptions, I see are:
1. qwindowsysteminterface, which can be renamed at some point to be
qplatformwindowsystemitnterface
2. qgenericplugin, which can also be renamed

So, let's rename _qpa.h to qplatform*_p.h. Ok?

Girish