Re: [PATCH] Documentation/CodingGuidelines: How to document new APIs

From: Stefan Beller <sbeller@google.com>
Date: Sep 28, 2018, 17:14 UTC
Message-ID: <CAGZ79kZzR+n+8ODs3SBhOEXFbOmccugOampzkpFKGoEXjggEwQ@mail.gmail.com>
In-Reply-To: <20180928011129.GD11281@sigill.intra.peff.net>

On Thu, Sep 27, 2018 at 6:11 PM Jeff King <peff@peff.net> wrote:

Show 15 quoted lines

>
> 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/technical, so let's state that in the guidelines.
> >
> > I disagree with this.  I think we should put all the API docs in the
> > header file, like we're already doing in e.g. strbuf.h.
>
> Me too.
>
> 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 function is clearly header level.

> (Though actually, those are the thing that I would not mind at all if
> they get formatted into real manpages and shipped to end users. We do
> not expect most users to dissect our file-formats, but they could at
> least be useful to somebody poking around).

Formats are sensible thing to present to the end user. I was also thinking about partial-clone, which is a concept rather than a format.

Show 6 quoted lines

>
> > Do you have a link to where in the discussion this split-docs strategy
> > was decided?
>
> I think the purpose of this patch is to spur people towards a decision.
> :)

For me it might end up in an exercise of writing clear and concise English. Though after reading Junios patch below, I would hope that may find consensus.

Stefan