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

[Patrick Steinhardt <ps@pks.im>]

On Tue, May 13, 2025 at 07:22:26PM -0300, Lucas Seiki Oshiro wrote:
> > 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