Re: [PATCH] document string_list_clear

[Jeff King <peff@peff.net>]

On Fri, Dec 12, 2014 at 11:19:23AM -0800, Stefan Beller wrote:

> * Assuming we put everything into headers now, we'd need to discuss
>   -> Do we want to extract it to technical/api-$somedoc later at all?
> (There seems to be some disagreement?)
>   -> How do we extract (plain sed for lines starting with "*", or
> doxygen, or a self cooked script)
>   -> How do we ensure the generated documentation doesn't get stale over time?

I think it would be _nice_ to extract it, and that should be a
consideration when doing the manual work of moving it into headers
(you'll notice I used the "/**" convention to start comments which
should be extractable, but I am happy to use any similar convention[1]).

But unless somebody is excited about working on the extractor
immediately, I think we should punt on it for now. Moving the
documentation is already a big job, and I do not want to add an extra
dependency to the task.

The exact extractor choice might influence formatting decisions (e.g.,
should extracted text stand alone, or must it be viewed in context of the
function it prefaces), but we might be able to do a mechanical
conversion later if those facts change.

-Peff