On Fri, Sep 28, 2018 at 09:50:14AM -0700, Junio C Hamano wrote: > -- >8 -- > Subject: CodingGuidelines: document the API in *.h files > > It makes it harder to let the API description and the reality drift > apart if the doc is kept close to the implementation or the header > of the API. We have been slowly migrating API docs out of the > Documentation/technical/api-* to *.h files, and the development > community generally considers that how inline docs in strbuf.h is > done the best current practice. > > We recommend documenting in the header over documenting near the > implementation to encourage people to write the docs that are > readable without peeking at the implemention.
Yeah, I agree with all of that rationale. > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index 6d265327c9..e87090c849 100644 > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -385,7 +385,11 @@ For C programs: > string_list for sorted string lists, a hash map (mapping struct > objects) named "struct decorate", amongst other things. > > - - When you come up with an API, document it. > + - When you come up with an API, document it the functions and the > + structures in the header file that exposes the API to its callers. > + Use what is in "strbuf.h" as a model to decide the appropriate tone > + in which the description is given, and the level of details to put > + in the description. I like the general idea here. I had trouble parsing the "in which the description is given". Maybe just: When you come up with an API, document its functions and structures in the header file that exposes the API to its callers. Use what is in "strbuf.h" as a model for the appropriate tone and level of detail. I like the idea you mentioned elsewhere of polishing up strbuf.h to serve as the model (but I don't want to hold up this much simpler patch if that seems likely to drag on). Thanks for pushing this towards a concrete conclusion. -Peff
