Re: [PATCH] document string_list_clear

Jeff King [off-list ref] 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).