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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 12, 2015, 23:01 UTC
Message-ID: <xmqqh9uqpwe9.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20150116090225.GA30797@peff.net>

Jeff King <peff@peff.net> writes:

Show 18 quoted lines

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