Junio C Hamano <gitster@xxxxxxxxx> writes: > "Linus Arver via GitGitGadget" <gitgitgadget@xxxxxxxxx> 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
