Lucas Seiki Oshiro <lucasseikioshiro@xxxxxxxxx> 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?
