[GSoC PATCH] json-writer: add docstrings to jw_* functions

[GSoC PATCH] json-writer: add docstrings to jw_* functions

[Lucas Seiki Oshiro]

Add a docstring for each function that manipulates json_writers.
---
Hi!

Given that my GSoC project needs some form of formatting JSON output, the
already existent json-writer.{ch} will be extremely useful. So, before
GSoC actually starts, I decided to study a little about json-writer and
just found that it doesn't have docstrings.

Here I'm documenting what each function does, as this module is a general
utility that can be used in any place of the Git codebase and other people
may be in the same position of studying of it does by directly reading its
source code.

PS: I'm sending this as single patch as many docstrings are similar and
json_writer was introduced in a single patch (7545941). But I can break
it into smaller patches if you prefer :-).

 json-writer.h | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)

diff --git a/json-writer.h b/json-writer.h
index 04413bd1af..aa513e86cb 100644
--- a/json-writer.h
+++ b/json-writer.h
@@ -69,42 +69,175 @@ 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.
+ */
 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.
+ */
 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 can be used for specifying the number
+ * of decimals after the point, using -1 for formatting with the maximum
+ * precision available.
+ */
 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.
+ */
 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.
+ */
 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.
+ */
 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.
+ */
 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.
+ */
 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, given the field key.
+ */
 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, given the field key.
+ */
 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.
+ */
 void jw_array_string(struct json_writer *jw, const char *value);
+
+/*
+ * Append an int value to the current array of the json_writer.
+ */
 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 can be used for specifying the number of decimals after the point,
+ * using -1 for formatting with the maximum precision available.
+ */
 void jw_array_double(struct json_writer *jw, int precision, double value);
+
+/*
+ * Append a true value to the current array of the json_writer.
+ */
 void jw_array_true(struct json_writer *jw);
+
+/*
+ * Append a false value to the current array of the json_writer.
+ */
 void jw_array_false(struct json_writer *jw);
+
+/*
+ * Append a boolean value to the current array of the json_writer.
+ */
 void jw_array_bool(struct json_writer *jw, int value);
+
+/*
+ * Append a null value to the current array of the json_writer.
+ */
 void jw_array_null(struct json_writer *jw);
+
+/*
+ * Append a value to the current array of the json_writer, given the
+ * json_writer that represents its content.
+ */
 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.
+ *
+ * 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.
+ */
 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.
+ */
 void jw_array_inline_begin_object(struct json_writer *jw);
+
+/*
+ * Start an array as a value in the current array.
+ */
 void jw_array_inline_begin_array(struct json_writer *jw);
 
+/*
+ * Return if 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)

Re: [GSoC PATCH] json-writer: add docstrings to jw_* functions

[Junio C Hamano]

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

> Add a docstring for each function that manipulates json_writers.
> ---
> Hi!
>
> Given that my GSoC project needs some form of formatting JSON output, the
> already existent json-writer.{ch} will be extremely useful. So, before
> GSoC actually starts, I decided to study a little about json-writer and
> just found that it doesn't have docstrings.
>
> Here I'm documenting what each function does, as this module is a general
> utility that can be used in any place of the Git codebase and other people
> may be in the same position of studying of it does by directly reading its
> source code.
>
> PS: I'm sending this as single patch as many docstrings are similar and
> json_writer was introduced in a single patch (7545941). But I can break
> it into smaller patches if you prefer :-).

Needs sign-off.

> +/*
> + * 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);

These are not strictly wrong per-se in the sense that you can indeed
write a "top-level" array by array-begin, followed by array-string,
etc., and finish it with end.  But such an array can be embedded as
a sub data structure in another json-writer with array-sub-jw or
object-sub-jw and once it is done, it is not "top-level" at all.

Perhaps it may be beneficial to give an overview of the API design,
at the beginning of the file (in other words, not a per-function
comment, but a comment covers the whole json-writer API), to outline
the concepts and philosophy the json-writer takes to build json
objects, perhaps?  Covering (I am not trying to be exhaustive here,
but merely giving ideas):

 - json_writer is to build a "collection", which is either an object
   or an array.  An object is a set of key-value pair where keys are
   always strings and values can be of various types (including
   objects and arrays).  An array is an ordered set of values, which
   can be of various types (including objects and arrays).

 - you open an object with object-begin, define one key-value pair
   at a time using various jw_object_<type> functions, and conclude
   with jw-end.

 - you open an array with array-begin, append one value at a  tie
   using various jw_array_<type> functions, and conclude with
   jw-end.

or something along that line, perhaps?

Re: [GSoC PATCH] json-writer: add docstrings to jw_* functions

[Lucas Seiki Oshiro]

> But such an array can be embedded as a sub data structure in another
> json-writer with array-sub-jw or object-sub-jw and once it is done,
> it is not "top-level" at all.

Hmmmmm... Perhaps it would be better to replace it by something like
"the main data structure" instead of "top-level structure"?

> Perhaps it may be beneficial to give an overview of the API design,
> at the beginning of the file (in other words, not a per-function
> comment, but a comment covers the whole json-writer API), to outline
> the concepts and philosophy the json-writer takes to build json
> objects, perhaps?

The beginning of json_writer.h already provides a good overview of
what it does, but not exactly to the functions. It also provides a
reference to its associated test (which can be used as examples), but
yeah, it is not exactly an API overview.

> - json_writer is to build a "collection", which is either an object
>   or an array.  An object is a set of key-value pair where keys are
>   always strings and values can be of various types (including
>   objects and arrays).  An array is an ordered set of values, which
>   can be of various types (including objects and arrays).

I think the already existing description covers those higher-level
aspects well enough.

> or something along that line, perhaps?

I liked it, and I'm working on it. But still, wouldn't it be nice
to have descriptions on each function? An overview like that is
enough for me for understanding most functions, but some are not so
clear (e.g. jw_array_argc_argv and jw_array_argv). Or, to not
being too verbose and repetitive only focusing in the less obvious
ones?

Thanks again, Junio!

PS: I'm cc'ing the e-mail address of Jeff Hostetler provided in
the latest commit created by him, since the first message couldn't
be delivered. He was the author of json_writer and I sent the patch
cc'ing the e-mail from the commit that introduced it.