Subject: Re: [PATCH] document string_list_clear

From: Junio C Hamano <[email-masked]>
Date: Tue, 09 Dec 2014 11:41:44 -0800

Jeff King <[email-masked]> 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).