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

[Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>]

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

> 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

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