Heads-up for developers working _on_ KF modules: how to mark deprecated API from now on

[Friedrich W. H. Kossebau]

Hi,

tldr; For deprecated API of KDE Frameworks modules please use 
ECMGenerateExportHeader and the respective macros to mark & wrap deprecated 
API, otherwise the whole effort breaks down. Question: where would you expect 
the documentation for how to do this?


The introduction of ECMGenerateExportHeader to KDE Frameworks has been 
completed now, all 34 KF modules having deprecated C++ API have been adapted 
to use the CMake macro ecm_generate_export_header as well as the new C++ 
macros available from the respective generated export header.

So whenever there is some API to be deprecated, its declaration would now be 
decorated like this:

#if KFOO_ENABLE_DEPRECATED_SINCE(5, x)
/**
 * @deprecated Since 5.x. Use bar(). // Sadly doxygen needs data duplicated
 */
KFOO_DEPRECATED_VERSION(5, x, "Use bar()")
void foo();
#endif

The version 5.x needs to be listed with the DEPRECATION_VERSIONS argument of 
the ecm_generate_export_header, otherwise at least KFOO_DEPRECATED_VERSION(5, 
x, "") will fail to build (you will run into this for sure as I did, just 
needs remembering, so start now :) ).

A perfect programming language would not need all this fragile duplication, 
but with current C++ this seems the closest we can do to support users of our 
libraries to control visibility of deprecated API and warnings about it, as 
well as help ourselves during ABI breaks to do smoother porting and see the 
legacy API that can be dropped.


There are some more details around all this (like when not to use the #if 
wrapper because building-against-library compiler needs to always see virtual 
methods or enum values, or disabling deprecated API from the library build 
itself using KFOO_BUILD_DEPRECATED_SINCE), my question now is where this is 
best documented in detail. I already added small snippets in some places, but 
still search for a place documenting all known cases and pitfalls.

So, if in need of guidance how to use the new deprecation mechanisms, where 
would you expect to find the help? Many answers wanted here.

Cheers
Friedrich