Add total bytes written public field to the JSON writer, by moving it…

… from internal. (#2102)

* Add total bytes written public field to the JSON writer, by moving it
from internal.

* Add doc comments to internal json writer fields.

* Fix typo in comment, close bracket.

sdk/inc/azure/core/az_json.h

@@ -303,17 +303,39 @@ AZ_NODISCARD AZ_INLINE az_json_writer_options az_json_writer_options_default()
  */
 typedef struct
 {
+  /// The total number of bytes written by the #az_json_writer to the output destination buffer(s).
+  /// This read-only field tracks the number of bytes of JSON written so far, and it shouldn't be
+  /// modified by the caller.
+  int32_t total_bytes_written;
+
   struct
   {
+    /// The destination to write the JSON into.
     az_span destination_buffer;
-    int32_t bytes_written;
-    // For single contiguous buffer, bytes_written == total_bytes_written
-    int32_t total_bytes_written; // Currently, this is primarily used for testing.
+
+    /// The bytes written in the current destination buffer.
+    int32_t bytes_written; // For single contiguous buffer, bytes_written == total_bytes_written
+
+    /// Allocator used to support non-contiguous buffer as a destination.
     az_span_allocator_fn allocator_callback;
+
+    /// Any struct that was provided by the user for their specific implementation, passed through
+    /// to the #az_span_allocator_fn.
     void* user_context;
+
+    /// A state to remember when to emit a comma between JSON array and object elements.
     bool need_comma;
+
+    /// The current state of the writer based on the last token written, used for validating the
+    /// correctness of the JSON being written.
     az_json_token_kind token_kind; // needed for validation, potentially #if/def with preconditions.
+
+    /// The current state of the writer based on the last JSON container it is in (whether array or
+    /// object), used for validating the correctness of the JSON being written, and so it doesn't
+    /// overflow the maximum supported depth.
     _az_json_bit_stack bit_stack; // needed for validation, potentially #if/def with preconditions.
+
+    /// A copy of the options provided by the user.
     az_json_writer_options options;
   } _internal;
 } az_json_writer;

sdk/src/azure/core/az_json_writer.c

@@ -20,12 +20,12 @@ AZ_NODISCARD az_result az_json_writer_init(
   _az_PRECONDITION_NOT_NULL(out_json_writer);
 
   *out_json_writer = (az_json_writer){
+    .total_bytes_written = 0,
     ._internal = {
       .destination_buffer = destination_buffer,
       .allocator_callback = NULL,
       .user_context = NULL,
       .bytes_written = 0,
-      .total_bytes_written = 0,
       .need_comma = false,
       .token_kind = AZ_JSON_TOKEN_NONE,
       .bit_stack = { 0 },
@@ -46,12 +46,12 @@ AZ_NODISCARD az_result az_json_writer_chunked_init(
   _az_PRECONDITION_NOT_NULL(allocator_callback);
 
   *out_json_writer = (az_json_writer){
+    .total_bytes_written = 0,
     ._internal = {
       .destination_buffer = first_destination_buffer,
       .allocator_callback = allocator_callback,
       .user_context = user_context,
       .bytes_written = 0,
-      .total_bytes_written = 0,
       .need_comma = false,
       .token_kind = AZ_JSON_TOKEN_NONE,
       .bit_stack = { 0 },
@@ -391,7 +391,7 @@ AZ_INLINE void _az_update_json_writer_state(
     az_json_token_kind token_kind)
 {
   ref_json_writer->_internal.bytes_written += bytes_written_in_last;
-  ref_json_writer->_internal.total_bytes_written += total_bytes_written;
+  ref_json_writer->total_bytes_written += total_bytes_written;
   ref_json_writer->_internal.need_comma = need_comma;
   ref_json_writer->_internal.token_kind = token_kind;
 }

sdk/tests/core/test_az_json.c

@@ -375,7 +375,8 @@ static void test_json_writer_append_nested(void** state)
 
       az_span_to_str((char*)array, 200, az_json_writer_get_bytes_used_in_destination(&writer));
       assert_int_equal(7, az_span_size(az_json_writer_get_bytes_used_in_destination(&writer)));
-      assert_int_equal(7, writer._internal.total_bytes_written);
+      assert_int_equal(7, writer.total_bytes_written);
+      assert_int_equal(7, writer._internal.bytes_written);
       assert_string_equal(array, "[1,2,3]");
     }
 
@@ -666,7 +667,7 @@ static void test_json_writer_chunked(void** state)
     az_span_to_str(
         (char*)array,
         200,
-        az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer._internal.total_bytes_written));
+        az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer.total_bytes_written));
 
     assert_string_equal(
         array,
@@ -698,7 +699,7 @@ static void test_json_writer_chunked(void** state)
       az_span_to_str(
           (char*)array,
           200,
-          az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer._internal.total_bytes_written));
+          az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer.total_bytes_written));
 
       assert_string_equal(array, "0.000000000000001");
     }
@@ -716,7 +717,7 @@ static void test_json_writer_chunked(void** state)
       az_span_to_str(
           (char*)array,
           200,
-          az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer._internal.total_bytes_written));
+          az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer.total_bytes_written));
 
       assert_string_equal(array, "0");
     }
@@ -750,7 +751,7 @@ static void test_json_writer_chunked(void** state)
     az_span_to_str(
         (char*)array,
         200,
-        az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer._internal.total_bytes_written));
+        az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer.total_bytes_written));
 
     assert_string_equal(
         array,
@@ -795,7 +796,7 @@ static void test_json_writer_chunked(void** state)
     az_span_to_str(
         (char*)array,
         200,
-        az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer._internal.total_bytes_written));
+        az_span_slice(AZ_SPAN_FROM_BUFFER(json_array), 0, writer.total_bytes_written));
 
     assert_string_equal(
         array,
@@ -833,9 +834,7 @@ static void test_json_writer_chunked(void** state)
           (char*)array,
           200,
           az_span_slice(
-              AZ_SPAN_FROM_BUFFER(json_array),
-              0,
-              nested_object_builder._internal.total_bytes_written));
+              AZ_SPAN_FROM_BUFFER(json_array), 0, nested_object_builder.total_bytes_written));
 
       assert_string_equal(
           array,