From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 09 Dec 2014 19:41:44 GMT
Subject: Re: [PATCH] document string_list_clear
Message-ID: <xmqq388omwzr.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20141206053024.GE31301@peff.net>

Jeff King <peff@peff.net> writes:

> Also, I forgot to mention: if we consistently put the API docs into the
> header files and extracted it automatically into standalone documents,
> we would not need to have two places.
>
> This is something I've been meaning to look at for a long time, but it
> never quite makes the priority list. And my past experiences with tools
> like doxygen has been that they are complicated and have a lot of
> dependencies. It's been a long time since I've tried, though.

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