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
On Fri, Sep 28, 2018 at 10:14:12AM -0700, Stefan Beller wrote:
> > I think other high-level concepts that are _not_ APIs (e.g., file
> > formats, protocol, etc) could go into technical/.
>
> That is what I meant with high level concepts. Anything that talks
> about or implies the existence of a f
On Fri, 28 Sep 2018 at 18:51, Junio C Hamano wrote:
> 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.
s/implemention/implementation/
> - - When you come up with an API
On Thu, Sep 27, 2018 at 6:11 PM Jeff King wrote:
>
> On Thu, Sep 27, 2018 at 04:27:32PM -0700, Jonathan Nieder wrote:
>
> > > There are different opinions on how to document an API properly.
> > > Discussion turns out nobody disagrees with documenting new APIs on the
> > > function level in the he
Jeff King writes:
> On Thu, Sep 27, 2018 at 04:27:32PM -0700, Jonathan Nieder wrote:
>
>> > There are different opinions on how to document an API properly.
>> > Discussion turns out nobody disagrees with documenting new APIs on the
>> > function level in the header file and high level concepts i
On Thu, Sep 27, 2018 at 04:27:32PM -0700, Jonathan Nieder wrote:
> > There are different opinions on how to document an API properly.
> > Discussion turns out nobody disagrees with documenting new APIs on the
> > function level in the header file and high level concepts in
> > Documentation/techni
Hi,
Stefan Beller wrote:
> There are different opinions on how to document an API properly.
> Discussion turns out nobody disagrees with documenting new APIs on the
> function level in the header file and high level concepts in
> Documentation/technical, so let's state that in the guidelines.
I
On Thu, Sep 27 2018, Junio C Hamano wrote:
> Stefan Beller writes:
>
>> There are different opinions on how to document an API properly.
>> Discussion turns out nobody disagrees with documenting new APIs on the
>> function level in the header file and high level concepts in
>
> Looks conditiona
Stefan Beller writes:
> There are different opinions on how to document an API properly.
> Discussion turns out nobody disagrees with documenting new APIs on the
> function level in the header file and high level concepts in
Looks conditionally good ;-) Thanks for keeping the ball rolling.
I di
There are different opinions on how to document an API properly.
Discussion turns out nobody disagrees with documenting new APIs on the
function level in the header file and high level concepts in
Documentation/technical, so let's state that in the guidelines.
Signed-off-by: Stefan Beller
---
T
10 matches
Mail list logo
