more conversion docs

Author: grisumbras

include/boost/json/conversion.hpp

@@ -151,7 +151,7 @@ struct try_value_to_tag { };
 template<class T>
 struct is_string_like;
 
-/** Conversion category for strings.
+/** Conversion category constant for strings.
 
     String types are represented as JSON strings.
 
@@ -221,7 +221,7 @@ using string_category = std::integral_constant<
 template<class T>
 struct is_path_like;
 
-/** Conversion category for filesystem paths.
+/** Conversion category constant for filesystem paths.
 
     Paths are represented in JSON as strings.
 
@@ -301,7 +301,7 @@ using path_category = std::integral_constant<
 template<class T>
 struct is_sequence_like;
 
-/** Conversion category for sequences.
+/** Conversion category constant for sequences.
 
     Sequences are represented in JSON as arrays.
 
@@ -386,7 +386,7 @@ using sequence_category = std::integral_constant<
 template<class T>
 struct is_map_like;
 
-/** Conversion category for maps.
+/** Conversion category constant for maps.
 
     Maps are represented in JSON as objects. Such representation limits this
     category to 1-to-1 maps (as opposed to 1-to-many e.g. @ref std::multimap)
@@ -470,7 +470,7 @@ using map_category = std::integral_constant<
 template<class T>
 struct is_tuple_like;
 
-/** Conversion category for tuples.
+/** Conversion category constant for tuples.
 
     Tuples are represented in JSON as arrays.
 
@@ -528,7 +528,7 @@ struct is_null_like
     : std::false_type
 { };
 
-/** Conversion category for null types.
+/** Conversion category constant for null types.
 
     Null types are represented in JSON as the `null` literal.
 
@@ -607,7 +607,7 @@ using null_category = std::integral_constant<
 template<class T>
 struct is_described_class;
 
-/** Conversion category for described classes.
+/** Conversion category constant for described classes.
 
     Described classes are represented in JSON as objects with an element for
     each described data member. Described bases are flattened, that is members
@@ -687,7 +687,7 @@ using described_class_category = std::integral_constant<
 template<class T>
 struct is_described_enum;
 
-/** Conversion category for described enums.
+/** Conversion category constant for described enums.
 
     Described enums are serialized as strings when their value equals to a
     described enumerator, and as integers otherwise. The reverse operation
@@ -750,7 +750,7 @@ using described_enum_category = std::integral_constant<
 template<class T>
 struct is_variant_like;
 
-/** Conversion category for variants.
+/** Conversion category constant for variants.
 
     Variants are serialized the same way their active alternative is
     serialized. The opposite conversion selects the first alternative for which
@@ -815,7 +815,7 @@ using variant_category = std::integral_constant<
 template<class T>
 struct is_optional_like;
 
-/** Conversion category for optionals.
+/** Conversion category constant for optionals.
 
     Optionals are represented in JSON as `null` if not engaged (i.e. does not
     store a value), or as the stored type otherwise.
@@ -853,14 +853,21 @@ using optional_category = std::integral_constant<
 using unknown_category = std::integral_constant<
     conversion_category, conversion_category::unknown>;
 
-/** Determines the category of conversion of a type.
+/** Overrides the category of conversion of a type.
 
-    Provides the member constant `value` that is equal to an enumerator of
-    @ref conversion_category that represents the suitable conversion category
-    of T. The primary template attempts to deduce the category.
+    Specializations should provide the static member constant `value` that is
+    equal to an enumerator of @ref conversion_category that represents the
+    suitable conversion category of T in context `Ctx`.
 
-    Users can specialize the trait for their own types if the deduction fails.
-    For example:
+    The primary template's `value` is equal to @ref
+    conversion_category::unknown.
+
+    Use `void` for `Ctx` (the default) if the category should apply regardless
+    of context.
+
+    The third template parameter can be used for conditional specializations.
+
+    Usage example:
 
     @code
     namespace boost {
@@ -874,7 +881,7 @@ using unknown_category = std::integral_constant<
     } // namespace json
     @endcode
 
-    @see @ref value_from, @ref value_to, \<\<Custom Conversions>>.
+    @see \<\<Custom Conversions>>, @ref value_from, @ref value_to.
 */
 template<class T, class Ctx = void, class Enable = void>
 struct use_category;

include/boost/json/value_from.hpp

@@ -20,43 +20,61 @@ namespace json {
 
 /** Convert an object of type `T` to @ref value.
 
-    This function attempts to convert an object
-    of type `T` to @ref value using
+    This function attempts to convert an object of type `T` to @ref value using
 
-    @li one of @ref value's constructors,
+    - one of @ref value's constructors,
+    - a library-provided generic conversion, or
+    - a user-provided overload of `tag_invoke`.
 
-    @li a library-provided generic conversion, or
+    In order to perform the conversion the function selects an appropriate
+    implementation based on the types `T` and `Context` (if provided).
 
-    @li a user-provided overload of `tag_invoke`.
+    1. If `Context` is available and is not `std::tuple<C...>`
 
-    Out of the function supports default constructible types satisfying
-    {req_SequenceContainer}, arrays, arithmetic types, `bool`, `std::tuple`,
-    `std::pair`, `std::optional`, `std::variant`, `std::nullptr_t`, and structs
-    and enums described using Boost.Describe.
+       a. check if `use_category<T, Context>::value` is not
+          @ref conversion_category::unknown; otherwise
 
-    Conversion of other types is done by calling an overload of `tag_invoke`
-    found by argument-dependent lookup. Its signature should be similar to:
+       b. check if a `tag_invoke` overload from the list below that takes a
+          `Context const&` exists.
+
+    2. Otherwise, if `Context` is available, and is `std::tuple<C...>` repeat
+       steps **1** and **2** recursively for every `C` until either
+       step **1.a** or **1.b** succeeds for some `C`.
+
+    3. Failing that,
+
+       a. check if `use_category<T>::value` is not
+          @ref conversion_category::unknown; otherwise
+
+       b. check if a `tag_invoke` overload from the list below that takes only
+          2 parameters exists; otherwise
+
+       c. check if `T` is one of @ref value, @ref array, @ref object,
+          or @ref string; otherwise
+
+       d. check if `T` matches one of the categories of types described in the
+          table "Conversion categories" in \<\<Value Conversion>> section.
+
+    These steps determine both the appropriate category of conversion for `T`,
+    and, if necessary, the effective context `C` that will be used for
+    conversion. If the category is selected on steps **1.a**, **3.a**, **3.c**,
+    or **3.d**, the library provides a suitable conversion implementation.
+    If the category is selected on steps **2.b** or **3.b**, then a
+    user-provided `tag_invoke` overload is used.
+
+    The overloads of `tag_invoke` that will be considered by this function
+    are in the following list. Overloads that appear higher in the list have
+    higher priority.
 
     @code
     template< class FullContext >
     void tag_invoke( value_from_tag, value&, T, const Context&, const FullContext& );
-    @endcode
-
-    or
 
-    @code
     void tag_invoke( value_from_tag, value&, T, const Context& );
-    @endcode
 
-    or
-
-    @code
     void tag_invoke( value_from_tag, value&, T );
     @endcode
 
-    The overloads are checked for existence in that order and the first that
-    matches will be selected. <br>
-
     The `ctx` argument can be used either as a tag type to provide conversions
     for third-party types, or to pass extra data to the conversion function.