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

From: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
Date: May 13, 2025, 22:05 UTC
Message-ID: <CBE59EF3-4C4D-4FD0-80E7-D9BAF70EFDAB@gmail.com>
In-Reply-To: <aCG2XkW2lJ1qYHKW@pks.im>

> I don't think there's a need to add "Mentored-by" trailers to every
> commit just because we happen to be your mentors right now :) If we
> actually helped then sure, makes sense. But to the best of my knowledge
> we didn't, so I'd just leave them out for now.

Ok! But given that now both of you are helping me here I think it's fair to give at least a Helped-by :-)

Show 9 quoted lines

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

Show 5 quoted lines

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

Show 6 quoted lines

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

> Patrick

Thanks!