Re: [PATCH] document string_list_clear

From: Jeff King <peff@peff.net>
Date: Dec 10, 2014, 08:52 UTC
Message-ID: <20141210085201.GB29776@peff.net>
In-Reply-To: <xmqq61dkl8e3.fsf@gitster.dls.corp.google.com>

On Tue, Dec 09, 2014 at 03:18:28PM -0800, Junio C Hamano wrote:

Show 14 quoted lines

> Jonathan Nieder <jrnieder@gmail.com> writes:
> 
> > 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.
> 
> If the result becomes unparsable by AsciiDoc(or), those who
> AsciiDoc'ified the api-*.txt may feel unhappy.  I however strongly
> suspect that the primary consumer of these api-*.txt documents are
> consuming the text version, not AsciiDoc-to-html output.

Yeah, that was my point. They were not even asciidoc'd for a long time, then one contributor, who does not otherwise work on the code, volunteered to asciidoc them. AFAIK there are no regular developers who wanted this feature (but I do not know for sure, which is why I asked).

I do not _mind_ if they can be asciidoc'd, but if nobody does so, they are bound to develop formatting errors. And matching asciidoc syntax does come at a readability cost to the text.

Show 5 quoted lines

> The documentation that was written with an explicit purpose to serve
> as documentation would explain how each pieces fit in the whole
> system much better than a list of pieces extracted from per-function
> comments, unless the header comment that serves as the source of
> generated document is written carefully.

If we split the header files sanely (i.e., to match what would be one api-* file), then I had imagined each header file having a long free-form comment at the top giving the overview, followed by commented structures and functions, with possibly other free-form comments in the middle as necessary. That's what I did for the strbuf.h conversion I just sent.

> I am a bit hesitant to see us spending extra cycles either to
> reinvent doxygen (if we do our own) or working around quirks in
> third-party tools (if we decide to use existing ones).

Me too. That's what I hoped that we could come up with a form whose in-header source is readable enough that people would use it. Then there is really no tool necessary.

-Peff