Re: [PATCH] document string_list_clear

From: Jeff King <peff@peff.net>
Date: Dec 6, 2014, 05:30 UTC
Message-ID: <20141206053024.GE31301@peff.net>
In-Reply-To: <20141206020458.GR16345@google.com>

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

Show 16 quoted lines

> Stefan Beller wrote:
> 
> > Signed-off-by: Stefan Beller <sbeller@google.com>
> > ---
> >
> >  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