Re: [PATCH 0/7] migrate api-strbuf.txt into strbuf.h

[Jeff King <peff@peff.net>]

On Thu, Feb 12, 2015 at 03:01:18PM -0800, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > This is a re-roll of this series:
> >
> >   http://thread.gmane.org/gmane.comp.version-control.git/260922/focus=261374
> >
> > from early December to move the strbuf documentation into the header
> > file.
> >
> > And of course the elephant in the room is the other dozen or more
> > api-*.txt files. I'd propose to do this strbuf.h series (and possible
> > follow-ons mentioned above) and stop there for a bit. That will let us
> > form a more coherent opinion on whether we like this system in practice,
> > how it ages as functions are changed and added, etc. That might affect
> > how or if we end up converting other files.
> >
> > It does leave us in an inconsistent state (some documentation is in
> > Documentation/technical, and some is in the headers), but I think that
> > is largely where we're at today. IMHO this is a strict improvement
> > because at least the logical chunk of "strbuf" is now in a single place.
> 
> Is there a general concensus on the direction?
> 
> I am inclined to merge this to 'next', if there is a general
> understanding that we will try to make the headers _the_ single
> source of truth of the API by (1) not adding to api-*.txt without
> describing new things in the headers and (2) moving things from
> api-*.txt to corresponding headers when clarifying, fixing or
> updating the API.

I'm fine with that (unsurprisingly), but I would like to hear an "OK"
from Jonathan before going ahead.

-Peff