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

[Patrick Steinhardt <ps@pks.im>]

On Tue, May 13, 2025 at 07:05:21PM -0300, Lucas Seiki Oshiro wrote:
> > void jw_object_begin(struct json_writer *jw, int pretty);
> > 
> > I think it would be interesting to learn _when_ to use this function. Is
> > it mandatory to call it? Can it be nested? Why is there no corresponding
> > `jw_object_end()`?
> > 
> >> void jw_array_begin(struct json_writer *jw, int pretty);
> > 
> > Same questions here.
> 
> A JSON can be a list or an object, composed by other lists or objects.
> Those functions, then, define if the current json_writer will output a
> list or an object.
> 
> Internal lists and objects are declared with
> jw_{array, object}_inline_begin_{array, object}, depending if we want
> to begin a list or an object and depending if we want to begin it
> inside a list or an object.
> 
> In all those cases, there's no need to jw_object_end or jw_array_end.
> jw_end covers both.
> 
> >> void jw_object_string(struct json_writer *jw, const char *key,
> >>      const char *value);
> > 
> > What happens when called after `jw_array_begin()`? Same question is true
> > for all the other `jw_object_*` functions.
> 
> It raises a bug: "json-writer: array: not in array

Okay. Information like this is very valuable context to have in the
per-function docs.

> > 
> >> void jw_object_inline_begin_object(struct json_writer *jw, const char *key);
> >> 
> >> void jw_object_inline_begin_array(struct json_writer *jw, const char *key);
> > 
> > Do these nest? E.g. can you call `inline_begin_object()` multiple times?
> 
> They are only tested up to the second nesting level. However, based
> on the source code it looks like they should.
> 
> json_writer has a stack. The *inline_begin* functions basically append { or
> [ to the buffer and to the stack.
> 
> Perhaps it would be a good idea to include a test for those cases?

That would certainly be welcome :)

Patrick