Re: [PATCH] document string_list_clear

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