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
