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

From: Jeff King <peff@peff.net>
Date: Sep 28, 2018, 01:11 UTC
Message-ID: <20180928011129.GD11281@sigill.intra.peff.net>
In-Reply-To: <20180927232732.GA216193@aiede.svl.corp.google.com>

On Thu, Sep 27, 2018 at 04:27:32PM -0700, Jonathan Nieder wrote:

Show 7 quoted lines

> > 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/.

(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).

> 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. :)

-Peff