From 3b8deac3e93f139711c02b93dfd49d17e823b025 Mon Sep 17 00:00:00 2001 From: Juan Carrano Date: Tue, 25 Jun 2019 14:49:36 +0200 Subject: [PATCH 1/2] sys/ubjson: deprecate module. Summary for Users ================= Deprecation is scheduled for 2020.01. Users which depend on this module and cannot switch libraries may copy the code into to their own application. As expressed in PR #11724, the UBJSON module has issues which are not easy or worth fixing. Before removing the module, it should be marked as deprecated to give users time to either migrate to another library, or copy the code to their own private repo. The deprecation warning has been supressed from the unit tests. This has the ugly side-effect of supressing deprecation warning in other unit tests too, but that should not last long, only until the module is finally deleted. --- sys/include/ubjson.h | 5 +++-- tests/unittests/tests-ubjson/Makefile.include | 2 ++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/sys/include/ubjson.h b/sys/include/ubjson.h index 47bb1f0968..f89ee1f4e0 100644 --- a/sys/include/ubjson.h +++ b/sys/include/ubjson.h @@ -187,14 +187,15 @@ typedef enum { UBJSON_SIZE_ERROR, /**< the length of a field exceeded SSIZE_MAX */ } ubjson_read_callback_result_t; -struct ubjson_cookie; +struct __attribute__ ((deprecated("The UBJSON module will be removed in release 2020.01"))) ubjson_cookie; /** * @brief A cookie passed between the read and write functions. * @details You probably want to wrap the cookie in some other data structure, * which you retrieve with container_of() in the callback. */ -typedef struct ubjson_cookie ubjson_cookie_t; +typedef struct ubjson_cookie ubjson_cookie_t +__attribute__ ((deprecated("The UBJSON module will be removed in release 2020.01"))); /** * @brief Method called by ubjson_read() to get more data. diff --git a/tests/unittests/tests-ubjson/Makefile.include b/tests/unittests/tests-ubjson/Makefile.include index 10ade2f7a3..d4978f02bb 100644 --- a/tests/unittests/tests-ubjson/Makefile.include +++ b/tests/unittests/tests-ubjson/Makefile.include @@ -1,2 +1,4 @@ USEMODULE += ubjson USEMODULE += pipe + +CFLAGS += -Wno-error=deprecated-declarations From 2d782bc225003a56d1894311afacf4c0c3d65d49 Mon Sep 17 00:00:00 2001 From: Juan Carrano Date: Tue, 25 Jun 2019 15:19:16 +0200 Subject: [PATCH 2/2] sys/ubjson: add deprecation notices to the documentation. Add @deprecated doxygen tags to the module, the header and the main reader and writer functions. --- sys/include/ubjson.h | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/sys/include/ubjson.h b/sys/include/ubjson.h index f89ee1f4e0..df6fb16fe3 100644 --- a/sys/include/ubjson.h +++ b/sys/include/ubjson.h @@ -20,12 +20,16 @@ * @defgroup sys_ubjson Universal Binary JSON library * @ingroup sys_serialization * @brief Provides a library to read and write UBJSON serialized data + * + * @deprecated This module is deprecated and will be removed in release 2020.01. * @{ * * @file * @brief Headers for the UBJSON module * * @author René Kijewski + * + * @deprecated This module is deprecated and will be removed in release 2020.01. */ #ifndef UBJSON_H @@ -289,6 +293,10 @@ ubjson_read_callback_result_t ubjson_read_next(ubjson_cookie_t *__restrict cooki * * You probably want to wrap the cookie in some other data structure, * which you retrieve with container_of() in the callback. + * + * @deprecated This function and its containing module are deprecated and + * will be removed in release 2020.01. + * * @param[in] cookie The cookie that is passed to the callback function. * @param[in] read The function that is called to receive more data. * @param[in] callback The callback function. @@ -434,6 +442,10 @@ ubjson_read_callback_result_t ubjson_read_object(ubjson_cookie_t *__restrict coo * The programmer needs to ensure that the API is used correctly. * The library won't complain if you write multiple values that are not * inside an array or object. The result will just not be properly serialized. + * + * @deprecated This function and its containing module are deprecated and + * will be removed in release 2020.01 + * * @param[out] cookie The cookie that will be passed to ubjson_write_null() and friends. * @param[in] write_fun The function that will be called to write data. */