Re: [PATCH] document string_list_clear

From: Stefan Beller <sbeller@google.com>
Date: Dec 9, 2014, 19:48 UTC
Message-ID: <CAGZ79kbk4SXEXKzn-V8c4zCQU8m8ub+VkKhmub-bFoLZT1WWpA@mail.gmail.com>
In-Reply-To: <xmqq7fy0mx70.fsf@gitster.dls.corp.google.com>

On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 5 quoted lines

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