Re: [PATCH] document string_list_clear

From: Jeff King <peff@peff.net>
Date: Dec 12, 2014, 19:29 UTC
Message-ID: <20141212192938.GB21132@peff.net>
In-Reply-To: <CAGZ79kbKCRKyugTnnx34AkeqN0NDBL_J2yGky06E+263oQ_6hg@mail.gmail.com>

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

Show 6 quoted lines

> * 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