Re: [PATCH] document string_list_clear

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Dec 9, 2014, 22:23 UTC
Message-ID: <20141209222337.GA16345@google.com>
In-Reply-To: <20141209202738.GC12001@peff.net>

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