From: Stefan Beller <sbeller@google.com>
Date: Tue, 09 Dec 2014 23:07:48 GMT
Subject: Re: [PATCH] document string_list_clear
Message-ID: <20141209230748.GA3442@google.com>
In-Reply-To: <20141209224949.GB16345@google.com>

On Tue, Dec 09, 2014 at 02:49:50PM -0800, Jonathan Nieder wrote:
> 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?
> 
> And another:

this goes on top or replaces the previous one? (This applies cleanly on origin/master) 

> -- >8--
> Subject: put string-list API documentation in one place
> 
> Until recently (v1.8.0-rc0~46^2~5, 2012-09-12), the string-list API
> was documented in detail in Documentation/technical/api-string-list.txt
> and the header file contained section markers and some short reminders
> but little other documentation.
> 
> Since then, the header has acquired some more comments that are mostly
> identical to the documentation from technical/.  In principle that
> should help convenience, since it means one less hop for someone
> reading the header to find API documentation.  In practice,
> unfortunately, it is hard to remember that there is documentation in
> two places, and the comprehensive documentation of some functions in
> the header makes it too easy to forget that the other functions are
> documented at all (and where).
> 
> Add a comment pointing to Documentation/technical/ and remove the
> comments that duplicate what is written there.  Longer term, we may
> want to move all of the technical docs to header files and generate
> printer-ready API documentation another way, but that is a larger
> change for another day.
> 
> Short reminders in the header file are still okay.
> 
> Reported-by: Stefan Beller <sbeller@google.com>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---

Thanks a lot for this patch. It's improving the situation a lot.
No information is lost albeit many deleted lines, have a 

Reviewed-by: Stefan Beller <sbeller@google.com>