[GSoC PATCH v3 0/2] json-writer: describe the jw_* functions

[GSoC PATCH v3 0/2] json-writer: describe the jw_* functions

[Lucas Seiki Oshiro]

Hello, again!

In this v3 I did some minor adjustments based on the review of v2
(https://lore.kernel.org/git/20250512020935.73140-1-lucasseikioshiro@gmail.com/).

Lucas Seiki Oshiro (2):
  json-writer: add docstrings to jw_* functions
  json-writer: describe the usage of jw_* functions

 json-writer.c |   4 --
 json-writer.h | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 171 insertions(+), 4 deletions(-)

-- 
2.39.5 (Apple Git-154)

[GSoC PATCH v3 1/2] json-writer: add docstrings to jw_* functions

[Lucas Seiki Oshiro]

Add a docstring for each function that manipulates json_writers.

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Patrick Steinhardt <ps@pks.im>
Helped-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 json-writer.c |   4 --
 json-writer.h | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 143 insertions(+), 4 deletions(-)

diff --git a/json-writer.c b/json-writer.c
index 8c5187e9fd..34577dc25f 100644
--- a/json-writer.c
+++ b/json-writer.c
@@ -268,10 +268,6 @@ static void append_sub_jw(struct json_writer *jw,
 	strbuf_addbuf(&jw->json, &value->json);
 }
 
-/*
- * Append existing (properly terminated) JSON sub-data (object or array)
- * as-is onto the given JSON data.
- */
 void jw_object_sub_jw(struct json_writer *jw, const char *key,
 		      const struct json_writer *value)
 {
diff --git a/json-writer.h b/json-writer.h
index 04413bd1af..0e8e6c3ddc 100644
--- a/json-writer.h
+++ b/json-writer.h
@@ -69,42 +69,185 @@ struct json_writer
 	.open_stack = STRBUF_INIT, \
 }
 
+/*
+ * Initialize a json_writer with empty values.
+ */
 void jw_init(struct json_writer *jw);
+
+/*
+ * Release the internal buffers of a json_writer.
+ */
 void jw_release(struct json_writer *jw);
 
+/*
+ * Begin the json_writer using an object as the top-level data structure. If
+ * pretty is set to 1, the result will be a human-readable and indented JSON,
+ * and if it is set to 0 the result will be minified single-line JSON.
+ */
 void jw_object_begin(struct json_writer *jw, int pretty);
+
+/*
+ * Begin the json_writer using an array as the top-level data structure. If
+ * pretty is set to 1, the result will be a human-readable and indented JSON,
+ * and if it is set to 0 the result will be minified single-line JSON.
+ */
 void jw_array_begin(struct json_writer *jw, int pretty);
 
+/*
+ * Append a string field to the current object of the json_writer, given its key
+ * and its value. Trigger a BUG when not in an object.
+ */
 void jw_object_string(struct json_writer *jw, const char *key,
 		      const char *value);
+
+/*
+ * Append an int field to the current object of the json_writer, given its key
+ * and its value. Trigger a BUG when not in an object.
+ */
 void jw_object_intmax(struct json_writer *jw, const char *key, intmax_t value);
+
+/*
+ * Append a double field to the current object of the json_writer, given its key
+ * and its value. The precision parameter defines the number of significant
+ * digits, where -1 can be used for maximum precision. Trigger a BUG when not in
+ * an object.
+ */
 void jw_object_double(struct json_writer *jw, const char *key, int precision,
 		      double value);
+
+/*
+ * Append a boolean field set to true to the current object of the json_writer,
+ * given its key. Trigger a BUG when not in an object.
+ */
 void jw_object_true(struct json_writer *jw, const char *key);
+
+/*
+ * Append a boolean field set to false to the current object of the json_writer,
+ * given its key. Trigger a BUG when not in an object.
+ */
 void jw_object_false(struct json_writer *jw, const char *key);
+
+/*
+ * Append a boolean field to the current object of the json_writer, given its
+ * key and its value. Trigger a BUG when not in an object.
+ */
 void jw_object_bool(struct json_writer *jw, const char *key, int value);
+
+/*
+ * Append a null field to the current object of the json_writer, given its key.
+ * Trigger a BUG when not in an object.
+ */
 void jw_object_null(struct json_writer *jw, const char *key);
+
+/*
+ * Append a field to the current object of the json_writer, given its key and
+ * another json_writer that represents its content. Trigger a BUG when not in
+ * an object.
+ */
 void jw_object_sub_jw(struct json_writer *jw, const char *key,
 		      const struct json_writer *value);
 
+/*
+ * Start an object as the value of a field in the current object of the
+ * json_writer. Trigger a BUG when not in an object.
+ */
 void jw_object_inline_begin_object(struct json_writer *jw, const char *key);
+
+/*
+ * Start an array as the value of a field in the current object of the
+ * json_writer. Trigger a BUG when not in an object.
+ */
 void jw_object_inline_begin_array(struct json_writer *jw, const char *key);
 
+/*
+ * Append a string value to the current array of the json_writer. Trigger a BUG
+ * when not in an array.
+ */
 void jw_array_string(struct json_writer *jw, const char *value);
+
+/*
+ * Append an int value to the current array of the json_writer. Trigger a BUG
+ * when not in an array.
+ */
 void jw_array_intmax(struct json_writer *jw, intmax_t value);
+
+/*
+ * Append a double value to the current array of the json_writer. The precision
+ * parameter defines the number of significant digits, where -1 can be used for
+ * maximum precision. Trigger a BUG when not in an array.
+ */
 void jw_array_double(struct json_writer *jw, int precision, double value);
+
+/*
+ * Append a true value to the current array of the json_writer. Trigger a BUG
+ * when not in an array.
+ */
 void jw_array_true(struct json_writer *jw);
+
+/*
+ * Append a false value to the current array of the json_writer. Trigger a BUG
+ * when not in an array.
+ */
 void jw_array_false(struct json_writer *jw);
+
+/*
+ * Append a boolean value to the current array of the json_writer. Trigger a BUG
+ * when not in an array.
+ */
 void jw_array_bool(struct json_writer *jw, int value);
+
+/*
+ * Append a null value to the current array of the json_writer. Trigger a BUG
+ * when not in an array.
+ */
 void jw_array_null(struct json_writer *jw);
+
+/*
+ * Append a json_writer as a value to the current array of the
+ * json_writer. Trigger a BUG when not in an array.
+ */
 void jw_array_sub_jw(struct json_writer *jw, const struct json_writer *value);
+
+/*
+ * Append the first argc values from the argv array of strings to the current
+ * array of the json_writer. Trigger a BUG when not in an array.
+ *
+ * This function does not provide safety for cases where the array has less than
+ * argc values.
+ */
 void jw_array_argc_argv(struct json_writer *jw, int argc, const char **argv);
+
+/*
+ * Append a null-terminated array of strings to the current array of the
+ * json_writer. Trigger a BUG when not in an array.
+ */
 void jw_array_argv(struct json_writer *jw, const char **argv);
 
+/*
+ * Start an object as a value in the current array of the json_writer. Trigger a
+ * BUG when not in an array.
+ */
 void jw_array_inline_begin_object(struct json_writer *jw);
+
+/*
+ * Start an array as a value in the current array. Trigger a BUG when not in an
+ * array.
+ */
 void jw_array_inline_begin_array(struct json_writer *jw);
 
+/*
+ * Return whether the json_writer is terminated. In other words, if the all the
+ * objects and arrays are already closed.
+ */
 int jw_is_terminated(const struct json_writer *jw);
+
+/*
+ * Terminates the current object or array of the json_writer. In other words,
+ * append a ] if the current array is not closed or } if the current object
+ * is not closed.
+ *
+ * Abort the execution if there's no object or array that can be terminated.
+ */
 void jw_end(struct json_writer *jw);
 
 #endif /* JSON_WRITER_H */
-- 
2.39.5 (Apple Git-154)

[GSoC PATCH v3 2/2] json-writer: describe the usage of jw_* functions

[Lucas Seiki Oshiro]

Provide an overview of the set of functions used for manipulating
`json_writer`s, by describing what functions should be used for
each JSON-related task.

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Patrick Steinhardt <ps@pks.im>
Helped-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 json-writer.h | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/json-writer.h b/json-writer.h
index 0e8e6c3ddc..8f845d4d29 100644
--- a/json-writer.h
+++ b/json-writer.h
@@ -28,6 +28,34 @@
  * object/array) -or- by building them inline in one pass.  This is a
  * personal style and/or data shape choice.
  *
+ * USAGE:
+ * ======
+ *
+ * - Initialize the json_writer with jw_init.
+ *
+ * - Open an object as the main data structure with jw_object_begin.
+ *   Append a key-value pair to it using the jw_object_<type> functions.
+ *   Conclude with jw_end.
+ *
+ * - Alternatively, open an array as the main data structure with
+ *   jw_array_begin. Append a value to it using the jw_array_<type>
+ *   functions. Conclude with jw_end.
+ *
+ * - Append a new, unterminated array or object to the current
+ *   object using the jw_object_inline_begin_{array, object} functions.
+ *   Similarly, append a new, unterminated array or object to
+ *   the current array using the jw_array_inline_begin_{array, object}
+ *   functions.
+ *
+ * - Append other json_writer as a value to the current array or object
+ *   using the jw_{array, object}_sub_jw functions.
+ *
+ * - Extend the current array with an null-terminated array of strings
+ *   by using jw_array_argv or with a fixed number of elements of a
+ *   array of string by using jw_array_argc_argv.
+ *
+ * - Release the json_writer after using it by calling jw_release.
+ *
  * See t/helper/test-json-writer.c for various usage examples.
  *
  * LIMITATIONS:
-- 
2.39.5 (Apple Git-154)

Re: [GSoC PATCH v3 0/2] json-writer: describe the jw_* functions

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 1031 bytes --]

Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes:

> Hello, again!
>
> In this v3 I did some minor adjustments based on the review of v2
> (https://lore.kernel.org/git/20250512020935.73140-1-lucasseikioshiro@gmail.com/).
>

This version looks good to me, thanks for the update.

I do have some general suggestions (not requirements):
- It would be nice if these patch versions were inlined with the
  previous ones. Makes it easier to compare versions while reviewing.
- Perhaps include a range-diff to make it easier to review the changes
  in the new version compared to the last one.

I can totally recommend b4 (https://b4.docs.kernel.org/en/latest/), it
helps manage both of the points I mentioned :)

> Lucas Seiki Oshiro (2):
>   json-writer: add docstrings to jw_* functions
>   json-writer: describe the usage of jw_* functions
>
>  json-writer.c |   4 --
>  json-writer.h | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 171 insertions(+), 4 deletions(-)
>
> --
> 2.39.5 (Apple Git-154)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [GSoC PATCH v3 0/2] json-writer: describe the jw_* functions

[Junio C Hamano]

Karthik Nayak <karthik.188@gmail.com> writes:

> Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes:
>
>> Hello, again!
>>
>> In this v3 I did some minor adjustments based on the review of v2
>> (https://lore.kernel.org/git/20250512020935.73140-1-lucasseikioshiro@gmail.com/).
>>
>
> This version looks good to me, thanks for the update.

Yup, the result reads very well.  Thanks, all.

> I do have some general suggestions (not requirements):
> - It would be nice if these patch versions were inlined with the
>   previous ones. Makes it easier to compare versions while reviewing.

"git send-email --in-reply-to=..." is a good tool to use.

> - Perhaps include a range-diff to make it easier to review the changes
>   in the new version compared to the last one.

Here, "git format-patch --range-diff=..." can help when preparing the
patches to be sent.

> I can totally recommend b4 (https://b4.docs.kernel.org/en/latest/), it
> helps manage both of the points I mentioned :)

... and more, by helping on the receiving end, too ;-).