Subject: Re: [PATCH] document string_list_clear

From: Jeff King <[email-masked]>
Date: Sat, 6 Dec 2014 00:30:24 -0500

On Fri, Dec 05, 2014 at 06:04:58PM -0800, Jonathan Nieder wrote:

> Stefan Beller wrote:
> 
> > Signed-off-by: Stefan Beller <[email-masked]>
> > ---
> >
> >  Just stumbled accross this one and wasn't sure if it also frees up
> >  the memory involved.
> >
> >  string-list.h | 5 +++++
> >  1 file changed, 5 insertions(+)
> 
> Sounds reasonable.  Documentation/technical/api-string-list.txt
> documents these functions more fully.  The right balance between
> documenting things in two places vs. adding "see also" pointers vs.
> just putting the highlights in one of the two places isn't obvious to
> me.

Also, I forgot to mention: if we consistently put the API docs into the
header files and extracted it automatically into standalone documents,
we would not need to have two places.

This is something I've been meaning to look at for a long time, but it
never quite makes the priority list. And my past experiences with tools
like doxygen has been that they are complicated and have a lot of
dependencies. It's been a long time since I've tried, though.

-Peff