@@ -285,7 +285,7 @@ typedef struct
285285 */
286286AZ_NODISCARD AZ_INLINE az_json_writer_options az_json_writer_options_default ()
287287{
288- az_json_writer_options options = ( az_json_writer_options ) {
288+ az_json_writer_options options = {
289289 ._internal = {
290290 .unused = false,
291291 },
@@ -303,17 +303,39 @@ AZ_NODISCARD AZ_INLINE az_json_writer_options az_json_writer_options_default()
303303 */
304304typedef struct
305305{
306+ /// The total number of bytes written by the #az_json_writer to the output destination buffer(s).
307+ /// This read-only field tracks the number of bytes of JSON written so far, and it shouldn't be
308+ /// modified by the caller.
309+ int32_t total_bytes_written ;
310+
306311 struct
307312 {
313+ /// The destination to write the JSON into.
308314 az_span destination_buffer ;
309- int32_t bytes_written ;
310- // For single contiguous buffer, bytes_written == total_bytes_written
311- int32_t total_bytes_written ; // Currently, this is primarily used for testing.
315+
316+ /// The bytes written in the current destination buffer.
317+ int32_t bytes_written ; // For single contiguous buffer, bytes_written == total_bytes_written
318+
319+ /// Allocator used to support non-contiguous buffer as a destination.
312320 az_span_allocator_fn allocator_callback ;
321+
322+ /// Any struct that was provided by the user for their specific implementation, passed through
323+ /// to the #az_span_allocator_fn.
313324 void * user_context ;
325+
326+ /// A state to remember when to emit a comma between JSON array and object elements.
314327 bool need_comma ;
328+
329+ /// The current state of the writer based on the last token written, used for validating the
330+ /// correctness of the JSON being written.
315331 az_json_token_kind token_kind ; // needed for validation, potentially #if/def with preconditions.
332+
333+ /// The current state of the writer based on the last JSON container it is in (whether array or
334+ /// object), used for validating the correctness of the JSON being written, and so it doesn't
335+ /// overflow the maximum supported depth.
316336 _az_json_bit_stack bit_stack ; // needed for validation, potentially #if/def with preconditions.
337+
338+ /// A copy of the options provided by the user.
317339 az_json_writer_options options ;
318340 } _internal ;
319341} az_json_writer ;
@@ -390,18 +412,17 @@ az_json_writer_get_bytes_used_in_destination(az_json_writer const* json_writer)
390412/**
391413 * @brief Appends the UTF-8 text value (as a JSON string) into the buffer.
392414 *
393- * @note If you receive an #AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is
394- * theoretically space, note that the JSON writer requires at least 64-bytes of slack within the
395- * output buffer, above the theoretical minimal space needed. The JSON writer pessimistically
396- * requires at least 64-bytes of space when writing any chunk of data larger than 10 characters
397- * because it tries to write in 64 byte chunks (10 character * 6 if all need to be escaped into the
398- * unicode form).
399- *
400415 * @param[in,out] ref_json_writer A pointer to an #az_json_writer instance containing the buffer to
401416 * append the string value to.
402417 * @param[in] value The UTF-8 encoded value to be written as a JSON string. The value is escaped
403418 * before writing.
404419 *
420+ * @note If you receive an #AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is
421+ * sufficient space, note that the JSON writer requires at least 64 bytes of slack within the
422+ * output buffer, above the theoretical minimal space needed. The JSON writer pessimistically
423+ * requires this extra space because it tries to write formatted text in chunks rather than one
424+ * character at a time, whenever the input data is dynamic in size.
425+ *
405426 * @remarks If \p value is #AZ_SPAN_EMPTY, the empty JSON string value is written (i.e. "").
406427 *
407428 * @return An #az_result value indicating the result of the operation.
@@ -420,20 +441,19 @@ AZ_NODISCARD az_result az_json_writer_append_string(az_json_writer* ref_json_wri
420441 * is, without any formatting or spacing changes. No modifications are made to this text, including
421442 * escaping.
422443 *
444+ * @note If you receive an #AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is
445+ * sufficient space, note that the JSON writer requires at least 64 bytes of slack within the
446+ * output buffer, above the theoretical minimal space needed. The JSON writer pessimistically
447+ * requires this extra space because it tries to write formatted text in chunks rather than one
448+ * character at a time, whenever the input data is dynamic in size.
449+ *
423450 * @remarks A single, possibly nested, JSON value is one that starts and ends with {} or [] or is a
424451 * single primitive token. The JSON cannot start with an end object or array, or a property name, or
425452 * be incomplete.
426453 *
427454 * @remarks The function validates that the provided JSON to be appended is valid and properly
428455 * escaped, and fails otherwise.
429456 *
430- * @note If you receive an #AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is
431- * theoretically space, note that the JSON writer requires at least 64-bytes of slack within the
432- * output buffer, above the theoretical minimal space needed. The JSON writer pessimistically
433- * requires at least 64-bytes of space when writing any chunk of data larger than 10 characters
434- * because it tries to write in 64 byte chunks (10 character * 6 if all need to be escaped into the
435- * unicode form).
436- *
437457 * @return An #az_result value indicating the result of the operation.
438458 * @retval #AZ_OK The provided \p json_text was appended successfully.
439459 * @retval #AZ_ERROR_NOT_ENOUGH_SPACE The destination is too small for the provided \p json_text.
@@ -456,6 +476,12 @@ az_json_writer_append_json_text(az_json_writer* ref_json_writer, az_span json_te
456476 * @param[in] name The UTF-8 encoded property name of the JSON value to be written. The name is
457477 * escaped before writing.
458478 *
479+ * @note If you receive an #AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is
480+ * sufficient space, note that the JSON writer requires at least 64 bytes of slack within the
481+ * output buffer, above the theoretical minimal space needed. The JSON writer pessimistically
482+ * requires this extra space because it tries to write formatted text in chunks rather than one
483+ * character at a time, whenever the input data is dynamic in size.
484+ *
459485 * @return An #az_result value indicating the result of the operation.
460486 * @retval #AZ_OK The property name was appended successfully.
461487 * @retval #AZ_ERROR_NOT_ENOUGH_SPACE The buffer is too small.
@@ -484,11 +510,10 @@ AZ_NODISCARD az_result az_json_writer_append_bool(az_json_writer* ref_json_write
484510 * @param[in] value The value to be written as a JSON number.
485511 *
486512 * @note If you receive an #AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is
487- * theoretically space, note that the JSON writer requires at least 64- bytes of slack within the
513+ * sufficient space, note that the JSON writer requires at least 64 bytes of slack within the
488514 * output buffer, above the theoretical minimal space needed. The JSON writer pessimistically
489- * requires at least 64-bytes of space when writing any chunk of data larger than 10 characters
490- * because it tries to write in 64 byte chunks (10 character * 6 if all need to be escaped into the
491- * unicode form).
515+ * requires this extra space because it tries to write formatted text in chunks rather than one
516+ * character at a time, whenever the input data is dynamic in size.
492517 *
493518 * @return An #az_result value indicating the result of the operation.
494519 * @retval #AZ_OK The number was appended successfully.
@@ -506,11 +531,10 @@ AZ_NODISCARD az_result az_json_writer_append_int32(az_json_writer* ref_json_writ
506531 * point and truncate the rest.
507532 *
508533 * @note If you receive an #AZ_ERROR_NOT_ENOUGH_SPACE result while appending data for which there is
509- * theoretically space, note that the JSON writer requires at least 64- bytes of slack within the
534+ * sufficient space, note that the JSON writer requires at least 64 bytes of slack within the
510535 * output buffer, above the theoretical minimal space needed. The JSON writer pessimistically
511- * requires at least 64-bytes of space when writing any chunk of data larger than 10 characters
512- * because it tries to write in 64 byte chunks (10 character * 6 if all need to be escaped into the
513- * unicode form).
536+ * requires this extra space because it tries to write formatted text in chunks rather than one
537+ * character at a time, whenever the input data is dynamic in size.
514538 *
515539 * @return An #az_result value indicating the result of the operation.
516540 * @retval #AZ_OK The number was appended successfully.
@@ -621,7 +645,7 @@ typedef struct
621645 */
622646AZ_NODISCARD AZ_INLINE az_json_reader_options az_json_reader_options_default ()
623647{
624- az_json_reader_options options = ( az_json_reader_options ) {
648+ az_json_reader_options options = {
625649 ._internal = {
626650 .unused = false,
627651 },
0 commit comments