On Fri, Sep 28, 2018 at 2:42 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > Stefan Beller <sbeller@xxxxxxxxxx> writes: > > > The previous patch suggested the strbuf header to be the leading example > > of how we would want our APIs to be documented. This may lead to some > > scrutiny of that code and the coding style (which is different from the > > API documentation style) and hence might be taken as an example on how > > to format code as well. > > > > So let's format strbuf.h in a way that we'd like to see: > > * omit the extern keyword from function declarations > > * name all parameters (usually the parameters are obvious from its type, > > but consider exceptions like > > `int strbuf_getwholeline_fd(struct strbuf *, int, int);` > > * break overly long lines > > > > Signed-off-by: Stefan Beller <sbeller@xxxxxxxxxx> > > --- > > > > Maybe this on top of Junios guideline patch? > > If we were to do this, I'd rather see us do a very good job on this > file first, with "We are going to use this file as the best current > practice model for an API header file" to begin its log message, > and then recommend its use as the model on top. I started going through that file and undoing "the naming all parameters" and additionally started to remove any obvious parameter name (mostly the first argument, that is of struct strbuf, and sometimes was called sb or out) But it seems in addition to all this we also want to re-read the documentation and make sure it reflects the API accurately and describes it well.
