Re: [PATCH] document string_list_clear

[Stefan Beller <sbeller@google.com>]

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.
But as we have some comments in the header for about half the functions there,
I missed looking into the Documentation at all.

I'd support Jeffs efforts to only write doc into the headers and then
export it or just
have documentation in the Documentation/technical dir. If there is
only one way to obtain
the information I wouldn't send in patches duplicating information.

Personally I first visit the header files to see if there is
documentation/comments on the
desired function. Looking at Documentation/technical/ is only reserved
for high lievel discussion on
API choices, so everything not prefixed with "api-" there.