From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 23 Apr 2024 23:27:08 GMT
Subject: Re: [PATCH v2 7/8] trailer: make trailer_info struct private
Message-ID: <xmqq34rb64oj.fsf@gitster.g>
In-Reply-To: <0e9ae049b8861fecf49c097e8d52e734f7a9c9b3.1713504153.git.gitgitgadget@gmail.com>

"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.

Other than that, looks "correct".