Lucas Seiki Oshiro <lucasseikioshiro@xxxxxxxxx> writes:
> Provide an overview of the set of functions used for manipulating
> json_writers by describing what functions should be used for each
> JSON-related task.
>
> Helped-by: Junio C Hamano <gitster@xxxxxxxxx>
> Mentored-by Patrick Steinhardt <ps@xxxxxx>
> Mentored-by: Karthik Nayak <karthik.188@xxxxxxxxx>
> Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@xxxxxxxxx>
> ---
> json-writer.h | 28 ++++++++++++++++++++++++++++
> 1 file changed, 28 insertions(+)
>
> diff --git a/json-writer.h b/json-writer.h
> index aa513e86cb..8b7470af67 100644
> --- a/json-writer.h
> +++ b/json-writer.h
> @@ -28,6 +28,34 @@
> * object/array) -or- by building them inline in one pass. This is a
> * personal style and/or data shape choice.
> *
> + * USAGE:
> + * ======
> + *
> + * - Initialize the json_writer with jw_init.
> + *
> + * - Open an object as the main data structure with jw_object_begin.
> + * Append a key-value pair to it using the jw_object_<type> functions.
> + * Conclude with jw_end.
> + *
> + * - Alternatively, open an array as the main data structure with
> + * jw_array_begin. Append a value to it using the jw_array_<type>
> + * functions. Conclude with jw_end.
> + *
> + * - Append a new, unterminated array or object to the current
> + * object using the jw_object_inline_begin_{array, object} functions.
> + * Similarly, append a new, unterminated array or object to
> + * the current array using the jw_array_inline_begin_{array, object}
> + * functions.
> + *
> + * - Append other json_writer as a value to the current array or object
> + * using the jw_{array, object}_sub_jw functions.
> + *
> + * - Extend the current array with an null-terminated array of strings
> + * by using jw_array_argv or with a fixed number of elements of a
> + * array of string by using jw_array_argc_argv.
> + *
> + * - Relase the json_writer after using it by calling jw_release.
> + *
s/Relase/Release
Overall this looks good, but I do have to wonder if it is needed given
that your previous patch already has documentation for each function. I
think more documentation is always better, but it shouldn't come at a
cost where we need to ensure that multiple sources of documentation need
to be updated to stay consistent with each other.
But I'll leave that decision to you.
Thanks for working on this!
> * See t/helper/test-json-writer.c for various usage examples.
> *
> * LIMITATIONS:
> --
> 2.39.5 (Apple Git-154)
Attachment:
signature.asc
Description: PGP signature
