On Fri, Aug 1, 2025 at 7:06 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > Given that even a long-time contributor gets confused (including me, > who needed to see where we documented this for our developers), > perhaps a clarification patch is in order? > > --- >8 --- > Subject: CodingGuidelines: clarify that S_release() does not reinitialize > > In the section for naming various API functions, the fact that > S_release() only releases the resources without preparing the > structure for immediate reuse becomes only apparent when you > readentries for S_release() and S_clear(). > > Clarify the description of S_release() a bit to make the entry self > sufficient. > > Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> > --- > Documentation/CodingGuidelines | 5 +++-- > 1 file changed, 3 insertions(+), 2 deletions(-) > > diff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines > index c1046abfb7..76ec6268f2 100644 > --- c/Documentation/CodingGuidelines > +++ w/Documentation/CodingGuidelines > @@ -610,8 +610,9 @@ For C programs: > - `S_init()` initializes a structure without allocating the > structure itself. > > - - `S_release()` releases a structure's contents without freeing the > - structure. > + - `S_release()` releases a structure's contents without reinitializing > + the structure for immediate reuse, and without freeing the structure > + itself. > > - `S_clear()` is equivalent to `S_release()` followed by `S_init()` > such that the structure is directly usable after clearing it. When Yeah, I think that could help. Thanks!
