Re: [PATCH] strbuf.h: format according to coding guidelines

2018-09-29 Thread Jeff King
On Fri, Sep 28, 2018 at 01:11:26PM -0700, Junio C Hamano wrote: > > I am mildly against giving names to obvious ones. > > Just to make sure nobody listening from sidelines do not > misunderstand, ones like getwholeline_fd() that takes more than one > parameter with the same time is a prime exampl

Re: [PATCH] strbuf.h: format according to coding guidelines

2018-09-28 Thread Stefan Beller
On Fri, Sep 28, 2018 at 2:42 PM Junio C Hamano wrote: > > Stefan Beller 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 differe

Re: [PATCH] strbuf.h: format according to coding guidelines

2018-09-28 Thread Junio C Hamano
Stefan Beller 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

Re: [PATCH] strbuf.h: format according to coding guidelines

2018-09-28 Thread Junio C Hamano
Junio C Hamano writes: > I actually do not mind the rule to be more like > > * Use the same parameter names used in the function declaration when >the description in the API documentation refers the parameter. Assuming that we adopt the above guideline, let's extending it to the original pa

Re: [PATCH] strbuf.h: format according to coding guidelines

2018-09-28 Thread Junio C Hamano
Junio C Hamano writes: > Stefan Beller writes: > >> So let's format strbuf.h in a way that we'd like to see: >> * omit the extern keyword from function declarations > > OK > >> * name all parameters (usually the parameters are obvious from its type, >> but consider exceptions like >> `int

Re: [PATCH] strbuf.h: format according to coding guidelines

2018-09-28 Thread Junio C Hamano
Stefan Beller writes: > So let's format strbuf.h in a way that we'd like to see: > * omit the extern keyword from function declarations OK > * name all parameters (usually the parameters are obvious from its type, > but consider exceptions like > `int strbuf_getwholeline_fd(struct strbuf *,

[PATCH] strbuf.h: format according to coding guidelines

2018-09-28 Thread Stefan Beller
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 cod