From 2b24cee2251fea3387c8a0b47968d288a5c11c75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 8 Feb 2023 12:52:06 +0100 Subject: [PATCH] Clarify MAGNUM_BUILD_DEPRECATED docs. The glTF importer plugin contains functionality that's present only in deprecated builds (backwards compatibility for skinning mesh attributes), which isn't causing any API signature difference but rather a difference in behavior. So expand the docs to say it's not limited to just APIs but features in general. --- doc/building.dox | 10 +++++----- doc/cmake.dox | 2 +- modules/FindMagnum.cmake | 2 +- src/Magnum/Magnum.h | 8 ++++---- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/building.dox b/doc/building.dox index 0c36a6ca9..df3a11e8f 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -677,11 +677,11 @@ Options controlling the build: versa. To some extent it's also possible to have only a subset of plugins built as static --- set `MAGNUM__BUILD_STATIC` for particular plugins to `ON` or `OFF` to override this option. -- `MAGNUM_BUILD_DEPRECATED` --- Include deprecated APIs in the build. Enabled - by default to preserve backwards compatibility, disabling it forces you to - update your code whenever there's a breaking API change. It's however - recommended to have this option disabled when deploying a final application - as it can result in smaller binaries. +- `MAGNUM_BUILD_DEPRECATED` --- Build with deprecated features included. + Enabled by default to preserve backwards compatibility, disabling it forces + you to update your code whenever there's a breaking change in the APIs or + in library behavior. It's however recommended to have this option disabled + when deploying a final application as it can result in smaller binaries. - `MAGNUM_DISTANCEFIELDCONVERTER_STATIC_PLUGINS`, `MAGNUM_FONTCONVERTER_STATIC_PLUGINS`, `MAGNUM_IMAGECONVERTER_STATIC_PLUGINS`, diff --git a/doc/cmake.dox b/doc/cmake.dox index a5fafc2d5..6c4921416 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -316,7 +316,7 @@ Features of found Magnum library are exposed in these CMake variables, they are also available as preprocessor variables if including @ref Magnum/Magnum.h "Magnum/Magnum.h": -- `MAGNUM_BUILD_DEPRECATED` --- Defined if compiled with deprecated APIs +- `MAGNUM_BUILD_DEPRECATED` --- Defined if compiled with deprecated features included - `MAGNUM_BUILD_STATIC` --- Defined if compiled as static libraries. Default are shared libraries. diff --git a/modules/FindMagnum.cmake b/modules/FindMagnum.cmake index 98ce451a4..b976cf9df 100644 --- a/modules/FindMagnum.cmake +++ b/modules/FindMagnum.cmake @@ -128,7 +128,7 @@ # # Features of found Magnum library are exposed in these variables: # -# MAGNUM_BUILD_DEPRECATED - Defined if compiled with deprecated APIs +# MAGNUM_BUILD_DEPRECATED - Defined if compiled with deprecated features # included # MAGNUM_BUILD_STATIC - Defined if compiled as static libraries # MAGNUM_BUILD_STATIC_UNIQUE_GLOBALS - Defined if static libraries keep the diff --git a/src/Magnum/Magnum.h b/src/Magnum/Magnum.h index 9603e140e..fc3007901 100644 --- a/src/Magnum/Magnum.h +++ b/src/Magnum/Magnum.h @@ -87,11 +87,11 @@ using Corrade::Utility::Fatal; #ifdef DOXYGEN_GENERATING_OUTPUT /** -@brief Build with deprecated API included +@brief Build with deprecated features included -Defined if the library contains deprecated API (which will be removed in the -future). To preserve backward compatibility, Magnum is by default built with -deprecated API included. +Defined if the library contains deprecated features and APIs (which will be +removed in the future). To preserve backward compatibility, Magnum is by +default built with deprecated features included. @see @ref building, @ref cmake */ /* This macro is enabled by default in Doxyfile, but we may still want to