From: Jeff King <peff@peff.net>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: Stefan Beller <sbeller@google.com>,
gitster@pobox.com, git@vger.kernel.org
Subject: Re: [PATCH] document string_list_clear
Date: Sat, 6 Dec 2014 00:30:24 -0500 [thread overview]
Message-ID: <20141206053024.GE31301@peff.net> (raw)
In-Reply-To: <20141206020458.GR16345@google.com>
On Fri, Dec 05, 2014 at 06:04:58PM -0800, Jonathan Nieder wrote:
> 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
next prev parent reply other threads:[~2014-12-06 5:30 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-12-06 1:51 [PATCH] document string_list_clear Stefan Beller
2014-12-06 2:04 ` Jonathan Nieder
2014-12-06 5:27 ` Jeff King
2014-12-06 5:30 ` Jeff King [this message]
2014-12-09 19:41 ` Junio C Hamano
2014-12-09 20:15 ` Jeff King
2014-12-09 20:21 ` Jonathan Nieder
2014-12-09 19:37 ` Junio C Hamano
2014-12-09 19:48 ` Stefan Beller
2014-12-09 20:17 ` Jonathan Nieder
2014-12-09 20:27 ` Jeff King
2014-12-09 20:32 ` Stefan Beller
2014-12-09 20:46 ` Jeff King
2014-12-09 22:23 ` Jonathan Nieder
2014-12-09 23:18 ` Junio C Hamano
2014-12-10 8:52 ` Jeff King
2014-12-10 8:43 ` Jeff King
2014-12-10 9:18 ` Jonathan Nieder
2014-12-12 9:16 ` Jeff King
2014-12-12 18:31 ` Jonathan Nieder
2014-12-12 19:17 ` Junio C Hamano
2014-12-12 19:19 ` Stefan Beller
2014-12-12 19:29 ` Jeff King
2014-12-12 19:24 ` Jeff King
2014-12-12 19:35 ` Jonathan Nieder
2014-12-12 21:27 ` Jeff King
2014-12-12 21:28 ` [PATCH 1/4] strbuf: migrate api-strbuf.txt documentation to strbuf.h Jeff King
2014-12-12 21:40 ` Jeff King
2014-12-12 22:16 ` Junio C Hamano
2014-12-12 22:30 ` Jonathan Nieder
2014-12-12 21:28 ` [PATCH 2/4] strbuf.h: drop asciidoc list formatting from API docs Jeff King
2014-12-12 22:19 ` Junio C Hamano
2014-12-12 22:37 ` Jonathan Nieder
2014-12-12 21:30 ` [PATCH 3/4] strbuf.h: format asciidoc code blocks as 4-space indent Jeff King
2014-12-12 22:39 ` Jonathan Nieder
2014-12-14 17:42 ` Michael Haggerty
2014-12-12 21:32 ` [PATCH 4/4] strbuf.h: reorganize api function grouping headers Jeff King
2014-12-12 22:46 ` Jonathan Nieder
2014-12-12 22:32 ` [PATCH] document string_list_clear Stefan Beller
2014-12-10 20:09 ` Michael Haggerty
2014-12-10 21:51 ` Jonathan Nieder
2014-12-10 22:28 ` Junio C Hamano
2014-12-10 22:37 ` Jonathan Nieder
2014-12-10 23:04 ` Junio C Hamano
2014-12-10 23:08 ` Jonathan Nieder
2014-12-09 22:49 ` Jonathan Nieder
2014-12-09 23:07 ` Stefan Beller
2014-12-09 23:15 ` Jonathan Nieder
2014-12-09 20:00 ` Jonathan Nieder
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20141206053024.GE31301@peff.net \
--to=peff@peff.net \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jrnieder@gmail.com \
--cc=sbeller@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).