From: Jonathan Nieder <jrnieder@gmail.com>
Date: Tue, 09 Dec 2014 20:21:52 GMT
Subject: Re: [PATCH] document string_list_clear
Message-ID: <20141209202152.GZ16345@google.com>
In-Reply-To: <20141209201551.GA12001@peff.net>

Jeff King wrote:
> On Tue, Dec 09, 2014 at 11:41:44AM -0800, Junio C Hamano wrote:

>> Yeah, that is a thought.
>>
>> Some existing documentation pages like allocation-growing may not be
>> a good match for this strategy, though; cache.h has a lot more than
>> just alloc-grow, and there needs to be a way to generate more than
>> one API docs from a single header (and vice versa, taking text from
>> more than one source for a single API, I suspect).
>
> I think that would be a matter of tool support for saying "now I am
> outputting api-foo" in the inline documentation[1]. It does make writing
> Makefiles a lot harder, though, if there isn't a one-to-one
> correspondence between targets and their sources. Perhaps it is a sign
> that we should split our include files more along functional boundaries.

Yeah, I think a separate alloc-grow.h would be fine.

Thanks,
Jonathan