From: Linus Arver <linusa@google.com>
Date: Thu, 25 Apr 2024 03:17:47 GMT
Subject: Re: [PATCH v2 7/8] trailer: make trailer_info struct private
Message-ID: <owlyzfti3zc4.fsf@fine.c.googlers.com>
In-Reply-To: <xmqq34rb64oj.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> There are a couple disadvantages:
>>
>>   (A) every time the member of the struct is accessed an extra pointer
>>       dereference must be done, and
>>
>>   (B) for users of trailer_info outside trailer.c, this struct can no
>>       longer be allocated on the stack and may only be allocated on the
>>       heap (because its definition is hidden away in trailer.c) and
>>       appropriately deallocated by the user.
>
>     (C) without good documentation on the API, the opaque struct is
>         hostile to programmers by going opposite to "Show me your
>         data structures, and I won't usually need your code; it'll
>         be obvious." mantra.
>
> The comment inside trailer.c does not count (the API users are not
> supposed to peek in it---that's the whole point of making the
> structure opaque).  You'd need to compensate with a bit more doc in
> trailer.h to help the API users.

SGTM. I can reroll again by the end of the week to add docs for would-be
API users. Cheers