== Deprecation of API ==

For example, you may have the following definition of a function which is published:
<source lang="cpp-qt">
#include <foo_export.h>
FOO_EXPORT void foo();
</source>

Where FOO_EXPORT is the macro holding the visibiity attribute, as defined in the included file "foo_export.h". That file usually is generated with a macro from CMake's [https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html GenerateExportHeader].

One marks the function as deprecated by noting it both in the API documentation as well as by an attribute to the compiler (duplication of data currently needed for the different tools). When using GenerateExportHeader, the export header file provides a macro "FOO_DEPRECATED" to do that for the compiler, as well as a convenience macro "FOO_EXPORT_DEPRECATED" which covers both visibility & deprecation attributes, for shorter code:
<source lang="cpp-qt">
#include <foo_export.h>
/**
 * @deprecated Since 5.0. Use bar().
 */
FOO_EXPORT_DEPRECATED void foo();
</source>

When using export macro headers generated by [https://api.kde.org/ecm/module/ECMAddQch.html ECMGenerateExportHeader], one would use the version-based macro "FOO_DEPRECATED_VERSION" and additionally the "FOO_ENABLE_DEPRECATED_SINCE" macro, like this (no combined macro available here):
<source lang="cpp-qt">
#include <foo_export.h>
#if FOO_ENABLE_DEPRECATED_SINCE(5, 0)
/**
 * @deprecated Since 5.0. Use bar().
 */
FOO_DEPRECATED_VERSION(5, 0, "Use bar()")
FOO_EXPORT void foo();
#endif
</source>
Again all the data duplication is needed in code and API documentation for the different processing tools.

9. @deprecated