From eae2613c68b89b705eb6af83df2c883dc15f5aa0 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sun, 7 Nov 2021 20:16:45 +0100 Subject: [PATCH] :memo: document deprecations --- doc/mkdocs/docs/api/basic_json/accept.md | 9 +++++++++ doc/mkdocs/docs/api/basic_json/from_bson.md | 14 +++++++++++++- doc/mkdocs/docs/api/basic_json/from_cbor.md | 12 ++++++++++++ doc/mkdocs/docs/api/basic_json/from_msgpack.md | 12 ++++++++++++ doc/mkdocs/docs/api/basic_json/from_ubjson.md | 12 ++++++++++++ doc/mkdocs/docs/api/basic_json/items.md | 5 ++++- doc/mkdocs/docs/api/basic_json/operator_gtgt.md | 6 ++++++ doc/mkdocs/docs/api/basic_json/operator_ltlt.md | 6 ++++++ doc/mkdocs/docs/api/basic_json/parse.md | 9 +++++++++ doc/mkdocs/docs/api/basic_json/sax_parse.md | 6 ++++++ 10 files changed, 89 insertions(+), 2 deletions(-) diff --git a/doc/mkdocs/docs/api/basic_json/accept.md b/doc/mkdocs/docs/api/basic_json/accept.md index f22de9db3..8794c585d 100644 --- a/doc/mkdocs/docs/api/basic_json/accept.md +++ b/doc/mkdocs/docs/api/basic_json/accept.md @@ -93,3 +93,12 @@ Linear in the length of the input. The parser is a predictive LL(1) parser. - Added in version 3.0.0. - Ignoring comments via `ignore_comments` added in version 3.9.0. + +!!! warning "Deprecation" + + Overload (2) replaces calls to `accept` with a pair of iterators as their first parameter which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp accept({ptr, ptr+len}, ...);` with `#!cpp accept(ptr, ptr+len, ...);`. + + You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated + function. diff --git a/doc/mkdocs/docs/api/basic_json/from_bson.md b/doc/mkdocs/docs/api/basic_json/from_bson.md index 747e2e4fd..77549370c 100644 --- a/doc/mkdocs/docs/api/basic_json/from_bson.md +++ b/doc/mkdocs/docs/api/basic_json/from_bson.md @@ -89,10 +89,22 @@ Linear in the size of the input. - [BSON specification](http://bsonspec.org/spec.html) - [to_bson](to_bson.md) for the analogous serialization -- [to_cbor](to_cbor.md) for the related CBOR format +- [from_cbor](from_cbor.md) for the related CBOR format - [from_msgpack](from_msgpack.md) for the related MessagePack format - [from_ubjson](from_ubjson.md) for the related UBJSON format ## Version history - Added in version 3.4.0. + +!!! warning "Deprecation" + + - Overload (2) replaces calls to `from_bson` with a pointer and a length as first two parameters, which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp from_bson(ptr, len, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`. + - Overload (2) replaces calls to `from_bson` with a pair of iterators as their first parameter, which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp from_bson({ptr, ptr+len}, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`. + + You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated + function. diff --git a/doc/mkdocs/docs/api/basic_json/from_cbor.md b/doc/mkdocs/docs/api/basic_json/from_cbor.md index 06d74cab8..3aa57b9ec 100644 --- a/doc/mkdocs/docs/api/basic_json/from_cbor.md +++ b/doc/mkdocs/docs/api/basic_json/from_cbor.md @@ -103,3 +103,15 @@ Linear in the size of the input. - Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0. - Added `allow_exceptions` parameter in version 3.2.0. - Added `tag_handler` parameter in version 3.9.0. + +!!! warning "Deprecation" + + - Overload (2) replaces calls to `from_cbor` with a pointer and a length as first two parameters, which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp from_cbor(ptr, len, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`. + - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp from_cbor({ptr, ptr+len}, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`. + + You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated + function. diff --git a/doc/mkdocs/docs/api/basic_json/from_msgpack.md b/doc/mkdocs/docs/api/basic_json/from_msgpack.md index 7665f8f9f..117c3865f 100644 --- a/doc/mkdocs/docs/api/basic_json/from_msgpack.md +++ b/doc/mkdocs/docs/api/basic_json/from_msgpack.md @@ -95,3 +95,15 @@ Linear in the size of the input. - Parameter `start_index` since version 2.1.1. - Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0. - Added `allow_exceptions` parameter in version 3.2.0. + +!!! warning "Deprecation" + + - Overload (2) replaces calls to `from_msgpack` with a pointer and a length as first two parameters, which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp from_msgpack(ptr, len, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`. + - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp from_msgpack({ptr, ptr+len}, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`. + + You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated + function. diff --git a/doc/mkdocs/docs/api/basic_json/from_ubjson.md b/doc/mkdocs/docs/api/basic_json/from_ubjson.md index 7ced89ea0..08117e89b 100644 --- a/doc/mkdocs/docs/api/basic_json/from_ubjson.md +++ b/doc/mkdocs/docs/api/basic_json/from_ubjson.md @@ -92,3 +92,15 @@ Linear in the size of the input. - Added in version 3.1.0. - Added `allow_exceptions` parameter in version 3.2.0. + +!!! warning "Deprecation" + + - Overload (2) replaces calls to `from_ubjson` with a pointer and a length as first two parameters, which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp from_ubjson(ptr, len, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`. + - Overload (2) replaces calls to `from_ubjson` with a pair of iterators as their first parameter, which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp from_ubjson({ptr, ptr+len}, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`. + + You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated + function. diff --git a/doc/mkdocs/docs/api/basic_json/items.md b/doc/mkdocs/docs/api/basic_json/items.md index ade372fff..f5b9bfc1d 100644 --- a/doc/mkdocs/docs/api/basic_json/items.md +++ b/doc/mkdocs/docs/api/basic_json/items.md @@ -90,8 +90,11 @@ When iterating over an array, `key()` will return the index of the element as st - Added `items` and deprecated `iterator_wrapper` in version 3.1.0. - Added structured binding support in version 3.5.0. -!!! note +!!! warning "Deprecation" This function replaces the static function `iterator_wrapper` which was introduced in version 1.0.0, but has been deprecated in version 3.1.0. Function `iterator_wrapper` will be removed in version 4.0.0. Please replace all occurrences of `#!cpp iterator_wrapper(j)` with `#!cpp j.items()`. + + You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated + function. diff --git a/doc/mkdocs/docs/api/basic_json/operator_gtgt.md b/doc/mkdocs/docs/api/basic_json/operator_gtgt.md index 2f699c92d..97c2f0b4e 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_gtgt.md +++ b/doc/mkdocs/docs/api/basic_json/operator_gtgt.md @@ -57,3 +57,9 @@ A UTF-8 byte order mark is silently ignored. ## Version history - Added in version 1.0.0 + +!!! warning "Deprecation" + + This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has + been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;` + with `#!cpp i >> j;`. diff --git a/doc/mkdocs/docs/api/basic_json/operator_ltlt.md b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md index d62aaaf34..0cba5ea3c 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_ltlt.md +++ b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md @@ -54,3 +54,9 @@ Linear. - Added in version 1.0.0 - Support for indentation character added in version 3.0.0. + +!!! warning "Deprecation" + + This function replaces function `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has + been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;` + with `#!cpp o << j;`. diff --git a/doc/mkdocs/docs/api/basic_json/parse.md b/doc/mkdocs/docs/api/basic_json/parse.md index 52f96b12d..95d876b0a 100644 --- a/doc/mkdocs/docs/api/basic_json/parse.md +++ b/doc/mkdocs/docs/api/basic_json/parse.md @@ -190,3 +190,12 @@ super-linear complexity. - Added in version 1.0.0. - Overload for contiguous containers (1) added in version 2.0.3. - Ignoring comments via `ignore_comments` added in version 3.9.0. + +!!! warning "Deprecation" + + Overload (2) replaces calls to `parse` with a pair of iterators as their first parameter which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp parse({ptr, ptr+len}, ...);` with `#!cpp parse(ptr, ptr+len, ...);`. + + You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated + function. diff --git a/doc/mkdocs/docs/api/basic_json/sax_parse.md b/doc/mkdocs/docs/api/basic_json/sax_parse.md index 3d54ad399..e2ac1b41d 100644 --- a/doc/mkdocs/docs/api/basic_json/sax_parse.md +++ b/doc/mkdocs/docs/api/basic_json/sax_parse.md @@ -107,3 +107,9 @@ A UTF-8 byte order mark is silently ignored. - Added in version 3.2.0. - Ignoring comments via `ignore_comments` added in version 3.9.0. + +!!! warning "Deprecation" + + Overload (2) replaces calls to `sax_parse` with a pair of iterators as their first parameter which has been + deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like + `#!cpp sax_parse({ptr, ptr+len});` with `#!cpp sax_parse(ptr, ptr+len);`.