conversion customization guidelines

Author: grisumbras

doc/qbk/conversion/guidelines.qbk

@@ -0,0 +1,42 @@
+[/
+    Copyright (c) 2023 Dmitry Arkhipov ([email protected])
+
+    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]

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]