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

From: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
Date: Apr 22, 2025, 21:24 UTC
Message-ID: <EE721541-8445-40EF-9AAD-ED88B3961546@gmail.com>
In-Reply-To: <xmqq7c3hb4cj.fsf@gitster.g>

> 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"?

Show 5 quoted lines

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

Show 5 quoted lines

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