From 0a7860fcfce7d66c0abe3d96f666540c00c33f73 Mon Sep 17 00:00:00 2001 From: Dmitry Arkhipov Date: Mon, 3 Jul 2023 17:58:35 +0300 Subject: [PATCH] conversion customization guidelines --- doc/qbk/conversion/guidelines.qbk | 42 +++++++++++++++++++++++++++++++ doc/qbk/conversion/overview.qbk | 1 + 2 files changed, 43 insertions(+) create mode 100644 doc/qbk/conversion/guidelines.qbk diff --git a/doc/qbk/conversion/guidelines.qbk b/doc/qbk/conversion/guidelines.qbk new file mode 100644 index 000000000..787380c5c --- /dev/null +++ b/doc/qbk/conversion/guidelines.qbk @@ -0,0 +1,42 @@ +[/ + Copyright (c) 2023 Dmitry Arkhipov (grisumbras@yandex.ru) + + Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + + Official repository: https://github.com/cppalliance/json +] + +[/-----------------------------------------------------------------------------] + + +[section Conversion customization guidelines] + +With so many options, it can be hard to choose the best way to customise +conversion for your type. In this section, we will discuss those options and +suggest which to choose when. + +The first advice is to use one of the library-provided conversions, rather +then providing a custom one, unless the resulting format is undesirable. If +the library deduces the wrong conversion category, you can opt out by +specialising the relevant trait to inherit from `std::false_type`. + +The next thing to consider is whether your conversions are intended for +internal use, or whether your users are not members of your team. If your users +are external, then they will ultimately determine the conditions in which these +conversions will be used. Conversely, for internal libraries and applications, +you have the full control of usage conditions. + +If your users are external, they and not you decide whether throwing exceptions +is acceptable. So, in this case it is better to use non-throwing `tag_invoke` +overloads. In addition, for customising conversion of composite types, always +use `tag_invoke` overload with 2 context parameters. This will allow correct +context propagation to elements of composites. This will also allow propagation +of exceptions from conversion of elements. + +Finally, it is worth mentioning that due to the ability to provide conversions +to JSON containers without a binary dependency on the library, you don't have +to push such dependency on your users. This is particularly relevant for +libraries for which interoperation with Boost.JSON is only extra functionality. + +[endsect] diff --git a/doc/qbk/conversion/overview.qbk b/doc/qbk/conversion/overview.qbk index 4d58a9a2b..032812509 100644 --- a/doc/qbk/conversion/overview.qbk +++ b/doc/qbk/conversion/overview.qbk @@ -23,5 +23,6 @@ from the standard library. [include alloc.qbk] [include context.qbk] [include forward.qbk] +[include guidelines.qbk] [endsect]