On Thu, Sep 27, 2018 at 6:11 PM Jeff King <peff@xxxxxxxx> 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 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. > > > 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
