Heads-up for developers working _on_ KF modules: how to mark deprecated API from now on
Friedrich W. H. Kossebau
kossebau at kde.org
Mon Oct 21 13:52:49 BST 2019
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()")
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.
More information about the kde-core-devel