From: Junio C Hamano <gitster@pobox•com>
To: Lucas Seiki Oshiro <lucasseikioshiro@gmail•com>
Cc: git@vger•kernel.org, jeffhost@microsoft•com
Subject: Re: [GSoC PATCH] json-writer: add docstrings to jw_* functions
Date: Fri, 18 Apr 2025 13:29:48 -0700 [thread overview]
Message-ID: <xmqq7c3hb4cj.fsf@gitster.g> (raw)
In-Reply-To: <20250418165651.14125-1-lucasseikioshiro@gmail.com> (Lucas Seiki Oshiro's message of "Fri, 18 Apr 2025 13:56:51 -0300")
Lucas Seiki Oshiro <lucasseikioshiro@gmail•com> writes:
> Add a docstring for each function that manipulates json_writers.
> ---
> Hi!
>
> Given that my GSoC project needs some form of formatting JSON output, the
> already existent json-writer.{ch} will be extremely useful. So, before
> GSoC actually starts, I decided to study a little about json-writer and
> just found that it doesn't have docstrings.
>
> Here I'm documenting what each function does, as this module is a general
> utility that can be used in any place of the Git codebase and other people
> may be in the same position of studying of it does by directly reading its
> source code.
>
> PS: I'm sending this as single patch as many docstrings are similar and
> json_writer was introduced in a single patch (7545941). But I can break
> it into smaller patches if you prefer :-).
Needs sign-off.
> +/*
> + * Begin the json_writer using an object as the top-level data structure. If
> + * pretty is set to 1, the result will be a human-readable and indented JSON,
> + * and if it is set to 0 the result will be minified single-line JSON.
> + */
> void jw_object_begin(struct json_writer *jw, int pretty);
> +
> +/*
> + * Begin the json_writer using an array as the top-level data structure. If
> + * pretty is set to 1, the result will be a human-readable and indented JSON,
> + * and if it is set to 0 the result will be minified single-line JSON.
> + */
> void jw_array_begin(struct json_writer *jw, int pretty);
These are not strictly wrong per-se in the sense that you can indeed
write a "top-level" array by array-begin, followed by array-string,
etc., and finish it with end. 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.
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? Covering (I am not trying to be exhaustive here,
but merely giving ideas):
- 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).
- you open an object with object-begin, define one key-value pair
at a time using various jw_object_<type> functions, and conclude
with jw-end.
- you open an array with array-begin, append one value at a tie
using various jw_array_<type> functions, and conclude with
jw-end.
or something along that line, perhaps?
next prev parent reply other threads:[~2025-04-18 20:29 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-04-18 16:56 [GSoC PATCH] json-writer: add docstrings to jw_* functions Lucas Seiki Oshiro
2025-04-18 20:29 ` Junio C Hamano [this message]
2025-04-22 21:24 ` Lucas Seiki Oshiro
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq7c3hb4cj.fsf@gitster.g \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=jeffhost@microsoft$(echo .)com \
--cc=lucasseikioshiro@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox