Re: [PATCH] document string_list_clear

[Jonathan Nieder <jrnieder@gmail.com>]

Jeff King wrote:

> Elsewhere I mentioned a tool to extract comments and format them. But do
> people actually care about the formatting step?

If formatting means "convert to a straightforward text document that I
can read through", then I do.

>                                                 Does anybody asciidoc
> the technical/api-* files? We did not even support building them until
> sometime in 2012. Personally, I only ever view them as text.

I also view them as text.  I tend to find it easier to read the
technical/api-* files than headers.  That might be for the same reason
that some other people prefer header files --- a
Documentation/technical/ file tends to be written in one chunk
together and ends up saying exactly what I need to know about the
calling sequence in a coherent way, while header files tend to evolve
over time to match the implementation without maintaining that
organization and usability.

I suspect a simple tool to extract the comments and produce something
like the technical/api-* files would help, since then when someone
writes a patch, they could try the tool and see if the result is still
easy to read.

Anyway, the patch I wrote was an attempt at a minimal fix (and an
attempt at getting out of a conversation that seemed to be moving
toward bikeshedding).  If someone wants to move the documentation from
api-strbuf.txt to strbuf.h, I won't object, since I hope that a simple
tool like described above isn't too far away.

Thanks,
Jonathan