Re: [GSoC PATCH v2 2/2] json-writer: describe the usage of jw_* functions

From: Patrick Steinhardt <ps@pks.im>
Date: May 14, 2025, 02:40 UTC
Message-ID: <aCQChKpJRD8zntBS@pks.im>
In-Reply-To: <F862E606-C784-433C-BAB1-283C678E20D5@gmail.com>

On Tue, May 13, 2025 at 07:22:26PM -0300, Lucas Seiki Oshiro wrote:

Show 13 quoted lines

> > 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.
> 
> Agreed, it looks like too much information. This second patch was
> created after the review of v1, and to be honest, I think that this
> overview is more clear as it focus in the what we want (write a JSON)
> instead of documenting each function.
> 
> So, if I need to choose one of them, I'll choose this.
> 
> > But I'll leave that decision to you.
> 
> Ok, I'll keep the second!

I think that both are useful. It's a common pattern to provide a high-level overview of how a certain subsystem is being used, but to also document how respective functions work. The former is useful to get a general understanding, whereas the latter is useful to get a better understanding of specific edge cases and how for example error handling works.

Patrick