✍ Heavy documentation improvements!

documentation/source/api/error handlers/replacement_handler.rst

@@ -31,7 +31,16 @@
 replacement_handler
 ===================
 
-The ``replacement_handler_t`` is the go-to error handling class. It is also the :doc:`ztd::text::default_handler </api/error handlers/default_handler>`.
+The ``replacement_handler_t`` is the go-to error handling class. It is also the :doc:`ztd::text::default_handler </api/error handlers/default_handler>` unless configured otherwise.
+
+Replacement works by using several different hooks on the provided encoding objects, or by falling back to some defaults if certain conditions are met. The user-controllable hooks are:
+
+- ``encoding.replacement_code_units(...)``, a function (which can be ``static`` or ``constexpr``) that returns a range of code units to insert directly into an output stream on a failed ``encode`` operation. It can also be called as a secondary backup if an ``decode`` operation fails, whereupon it will use the values in the range to attempt ``decode``\ ing them into the output if possible. It can be empty, to indicate that nothing is to be inserted.
+- ``encoding.replacement_code_points(...)``, a function (which can be ``static`` or ``constexpr``) that returns a range of code points to insert directly into an output stream on a failed ``decode`` operation. It can also be called as a secondary backup if an ``encode`` operation fails, whereupon it will use the values in the range to attempt ``encode``\ ing them into the output if possible. It can be empty, to indicate that nothing is to be inserted.
+- ``encoding.maybe_replacement_code_units(...)``, a function (which can be ``static`` or ``constexpr``) that returns a maybe-range. If the expression ``if (maybe_returned_range)`` evaluates to ``true``, it will get the range returned by the function by performing a dereference of ``decltype(auto) returned_range = *maybe_returned_range;``. If the conditional expression does not evaluate to ``true``, it will assume that nothing can be returned from the function. This is useful for runtime-only encodings or encodings that wrap other encodings and may not have a replacement function. The dereferenced returned range is used exactly as its non-\ ``maybe`` counterpart.
+- ``encoding.maybe_replacement_code_points(...)``, a function (which can be ``static`` or ``constexpr``) that returns a maybe-range. If the expression ``if (maybe_returned_range)`` evaluates to ``true``, it will get the range returned by the function by performing a dereference of ``decltype(auto) returned_range = *maybe_returned_range;``. If the conditional expression does not evaluate to ``true``, it will assume that nothing can be returned from the function. This is useful for runtime-only encodings or encodings that wrap other encodings and may not have a replacement function. The dereferenced returned range is used exactly as its non-\ ``maybe`` counterpart.
+
+Each replacement handler can take the current ``encode_state``/\ ``decode_state`` parameter for its desired operation, if it so chooses. This will allow replacements to hook into the statefulness of any given encoding operation. It fill first call ``replacement_code_units(state)`` first, if it's well-formed. Otherwise, it will call ``replacement_code_units()``. It will do this with each of the 4 replacement functions mentioned above.
 
 .. doxygenvariable:: ztd::text::replacement_handler
 

documentation/source/api/propagate_error.rst

@@ -31,6 +31,9 @@
 propagate_error
 ===============
 
-This helper function processes an error for a transcoding operation and shuffles a result through its decode and encode-step :doc:`error handlers</design/error handling>`.
+This helper function processes an error for a transcoding operation and shuffles a result through its decode step and encode step :doc:`error handlers</design/error handling>`. Nominally used after a solely decode portion of a transcode operation fails.
 
-.. doxygenfunction:: ztd::text::propagate_error
+If the user is doing a direct conversion and can simply call the encode portion of the error handler directly, calling this function can be skipped entirely by the user.
+
+.. doxygengroup:: ztd_text_transcode_helpers
+	:content-only:

documentation/source/design/error handling/error handler anatomy.rst

@@ -83,16 +83,16 @@ For example, someone can see if there is space left in the ``result.output`` par
 Third Parameter
 ---------------
 
-The third parameter is a contiguous range of inputs that were read. Typically, this is a ``ztd::span`` handed to you, or something that can construct a ``ztd::span`` or either code units or code points (whatever the input type has). This is useful for ``input_range``\ s and ``input_iterator``\ s where it is impossible to guarantee a value can be re-read, as is the case `with istream_iterator <https://en.cppreference.com/w/cpp/iterator/istream_iterator>`_ and other I/O-style iterators and ranges.
-
-This is useful for grabbing any unused-but-read input data, and storing it for later. For example, reading from a network buffer where the network still has more data means that getting a :doc:`ztd::text::encoding_error::incomplete_sequence </api/encoding_error>` is not **really** an error. It just means to save what has not been read yet, change the buffer pointer to leave those characters in the right place, and try again. This can also be done a little bit easier by utilizing the :doc:`ztd::text::incomplete_handler </api/error handlers/incomplete_handler>`.
+The third parameter is a contiguous range of input values that were read. Typically, this is a ``ztd::span`` handed to you, or something that can construct a ``ztd::span`` or either code units or code points (whatever the output type has). This is useful for ``input_range``\ s and ``input_iterator``\ s where it is impossible to guarantee a value can be written, as is the case `with istream_iterator <https://en.cppreference.com/w/cpp/iterator/istream_iterator>`_ and other I/O-style iterators and ranges.
 
 
 
 Fourth Parameter
 ----------------
 
-The fourth parameter is a contiguous range of outputs that were read. Typically, this is a ``ztd::span`` handed to you, or something that can construct a ``ztd::span`` or either code units or code points (whatever the output type has). This is useful for ``output_range``\ s and ``output_iterator``\ s where it is impossible to guarantee a value can be written, as is the case `with ostream_iterator <https://en.cppreference.com/w/cpp/iterator/ostream_iterator>`_ and other I/O-style iterators and ranges. It is also **very** important for when someone does bulk-buffered writes, since multiple writes are not guaranteed to fit within the given :doc:`ztd::text::max_code_points_v </api/max_code_points>` or :doc:`ztd::text::max_code_units_v </api/max_code_units>` for a specific encoding. (They only represent the maximum for a single, atomic operation.)
+The fourth parameter is a contiguous range of output values that were almost written to the output, but could not be because the output has no more room left. Typically, this is a ``ztd::span`` handed to you, or something that can construct a ``ztd::span`` or either code units or code points (whatever the input type has). This is particularly useful for ``output_range``\ s and ``output_iterator``\ s where there is no way to guarantee all characters will be successfully written, as is the case `with ostream_iterator <https://en.cppreference.com/w/cpp/iterator/ostream_iterator>`_ and other I/O-style iterators and ranges.
+
+The fourth parameter is only ever filled out if the error returned is :doc:`ztd::text::encoding_error::insufficient_output </api/encoding_error>`. It is **very** important for when someone does bulk-buffered writes, since multiple writes are not guaranteed to fit within the given :doc:`ztd::text::max_code_points_v </api/max_code_points>` or :doc:`ztd::text::max_code_units_v </api/max_code_units>` for a specific encoding. (They only represent the maximum for a single, atomic operation.)
 
 This is useful for grabbing any would-be-written output data, and storing it for later / completing it. For example, writing to a smaller, contiguous buffer for delivery and looping around that buffer can be faster, but it runs the risk of partial reads/writes on the boundaries of said smaller, contiguous buffer.
 

include/ztd/ranges/blackhole_iterator.hpp

@@ -79,7 +79,7 @@ namespace ztd { namespace ranges {
 		//////
 		using iterator_category = ::std::output_iterator_tag;
 		//////
-		/// @brief Standard @c std::ptrdiff_t @c difference_type definition.
+		/// @brief Standard `std::ptrdiff_t` `difference_type` definition.
 		//////
 		using difference_type = ::std::ptrdiff_t;
 		//////

include/ztd/ranges/counted_iterator.hpp

@@ -232,11 +232,10 @@ namespace ztd { namespace ranges {
 	//////
 	/// @brief A counted iterator that stores an iterator plus a count, which is used to iterator over the
 	/// specified count of elements. Useful for algorithms wherein the iterator is not random access but still
-	/// works on a given iterator and a size (e.g., the @c std::ranges::copy algorithm).
+	/// works on a given iterator and a size (e.g., the `std::ranges::copy` algorithm).
 	///
-	/// @tparam _It The Iterator to wrap. The count is a @c difference_type that is associated with the Iterator.
-	/// (The
-	/// @c difference_type is usually a signed type such as the @c ptrdiff_t type.)
+	/// @tparam _It The Iterator to wrap. The count is a `difference_type` that is associated with the Iterator.
+	/// (The `difference_type` is usually a signed type such as the `ptrdiff_t` type.)
 	//////
 	template <typename _It>
 	using counted_iterator =

include/ztd/ranges/default_sentinel.hpp

@@ -47,22 +47,16 @@ namespace ztd { namespace ranges {
 #if ZTD_IS_ON(ZTD_STD_LIBRARY_RANGES_I_)
 	//////
 	/// @brief A sentinel that cannot compare equal to any other iterator and thus results in infinitely long ranges.
-	///
-	//////
 	using default_sentinel_t = ::std::default_sentinel_t;
 #else
 	//////
 	/// @brief A sentinel that cannot compare equal to any other iterator and thus results in infinitely long ranges.
-	///
-	//////
 	struct default_sentinel_t { };
 #endif
 
 
 	//////
 	/// @brief An available and usable ztd::text::default_sentinel for ease of use.
-	///
-	//////
 	inline constexpr default_sentinel_t default_sentinel = {};
 
 	ZTD_RANGES_INLINE_ABI_NAMESPACE_CLOSE_I_