Re: [PATCH] document string_list_clear

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 9, 2014, 19:41 UTC
Message-ID: <xmqq388omwzr.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20141206053024.GE31301@peff.net>

Jeff King <peff@peff.net> writes:

Show 8 quoted lines

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