Subject: Re: [PATCH v2 6/8] trailer: make parse_trailers() return trailer_info pointer

From: Junio C Hamano <[email-masked]>
Date: Tue, 23 Apr 2024 16:17:08 -0700

"Linus Arver via GitGitGadget" <[email-masked]> writes:

> ... From the trailer API user's perspective, the call
> to trailer_info_new() can be replaced with parse_trailers(); do so in
> interpret-trailers.

And from the trailer API users' perspective, it would now help to
have a bit of comment on parse_trailers() function.  The users need
to know at least:

 - what the function returns (i.e. a pointer to an opaque
   trailer_info structure),

 - what operations can be done to the opaque structure, and 

 - what informations can be extracted out of the opaque structure.

When appropriately typed and named members in the structure are
visible, the latter two are obvious in well written programs, but
now you are going to hide the data structure, "Show me your data
structures, and I won't usually need your code; it'll be obvious."
would no longer work.  You'd need to compensate for making the
structure opaque to rob the clarity from the readers with good
comments to the function and the API to help them.

The changes in this patch look more-or-less obvious.  Looking good.