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