Re: [PATCH] document string_list_clear

[Jeff King <peff@peff.net>]

On Tue, Dec 09, 2014 at 12:17:13PM -0800, Jonathan Nieder wrote:

> Stefan Beller wrote:
> > On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> >> Perhaps the API doc that currently says "Free" is the only thing
> >> that needs fixing?  And perhaps add "See $doc" at the beginning of
> >> the header and remove duplicated comments we already have in the
> >> file?
> >
> > The reason I wrote this patch originally was because I seem to forget we have
> > more than one place to document our APIs. If there are comments in the header
> > I seem to have thought it were the only place where we have documentation.
> 
> How about this patch?
> 
> -- >8 --
> Subject: put strbuf API documentation in one place
> 
> v1.8.1-rc0~61^2 (strbuf_split*(): document functions, 2012-11-04)
> added some nice API documentation for a few functions to strbuf.h, to
> complement the documentation at Documentation/technical/api-strbuf.
> That was helpful because it meant one less hop for someone reading the
> header to find API documentation.
> 
> In practice, unfortunately, it is too hard to remember that there
> is documentation in two places.  The longer documentation comments
> in the header made Documentation/technical/api-strbuf less
> discoverable.  So move the information to
> Documentation/technical/api-strbuf and drop the long comments.
> 
> Hopefully in the long term we will find a good way to
> generate well organized Documentation/technical/api-* documents
> from comments in headers and this problem will be eliminated
> completely.
> 
> Short reminders in the header file are still okay.

I somewhat feel this goes in the opposite direction of where we want to
be (all data in one place, but that place is the header). Your patch
might make api-strbuf more discoverable, but it also vastly increases
the chances of function getting out of sync with their documentation, or
new functions being added without getting documented (very often the
presence of other documentation in the comments is enough to guilt me
into writing it for new ones).

Elsewhere I mentioned a tool to extract comments and format them. But do
people actually care about the formatting step? 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.

In which case can we simply start migrating api-strbuf.txt into
in-header comments, without worrying about a parsing tool?

-Peff