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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 18, 2025, 20:29 UTC
Message-ID: <xmqq7c3hb4cj.fsf@gitster.g>
In-Reply-To: <20250418165651.14125-1-lucasseikioshiro@gmail.com>

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

Show 17 quoted lines

> 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.

Show 13 quoted lines

> +/*
> + * 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?