[demo/patch 0/3] Re: [PATCH] Documentation: document the string-list macros.
- From
Jonathan Nieder <jrnieder@gmail.com>
- Date
- Sep 5, 2010, 20:03 UTC
- Message-ID
- <20100905200323.GA14497@burratino>
- In-Reply-To
- <1283709077-5438-1-git-send-email-tfransosi@gmail.com>
Thiago Farina wrote:
Show 16 quoted lines
> --- a/Documentation/technical/api-string-list.txt > +++ b/Documentation/technical/api-string-list.txt > @@ -52,6 +52,18 @@ However, if you use the list to check if a certain string was added > already, you should not do that (using unsorted_string_list_has_string()), > because the complexity would be quadratic again (but with a worse factor). > > +Macros > +------ > + > +`STRING_LIST_INIT_NODUP`:: > + > + Initialize the members and set the `strdup_strings` member to 0. > + > +`STRING_LIST_INIT_DUP`:: > + > + Initialize the members and set the `strdup_strings` member to 1.
After reading that, one might be tempted to write
struct string_list x; STRING_LIST_INIT_NODUP(x);
, no? In other words, I don't find the text very clear.
If you like working by example (like I do) then api-strbuf.txt might give a good indication of how this sort of thing can be helpfully documented.
Maybe something in this direction?
Patch #3 in particular is very rough and ought to be split up for easier review. This is not meant for application, just to give an idea.
Jonathan Nieder (3): string-list: introduce string_list_init() string-list: document ... Make initialization of string_lists more consistent
Documentation/technical/api-string-list.txt | 18 +++++++++------ builtin/apply.c | 8 +++--- builtin/blame.c | 4 +- builtin/clean.c | 2 +- builtin/commit.c | 4 +- builtin/fetch.c | 13 ++++------- builtin/fmt-merge-msg.c | 13 ++++++----- builtin/log.c | 9 ++----- builtin/mailsplit.c | 1 + builtin/notes.c | 4 +- builtin/remote.c | 30 +++++++++++++------------- builtin/shortlog.c | 25 ++++++++++++--------- diff-no-index.c | 1 + mailmap.c | 17 +++++++++----- mailmap.h | 2 +- merge-recursive.c | 16 ++++++++------ notes.c | 4 +- pretty.c | 5 ++- reflog-walk.c | 1 + resolve-undo.c | 8 +++--- revision.c | 7 ++++- string-list.c | 28 +++++++++++++++++++++--- string-list.h | 4 +++ submodule.c | 4 +- wt-status.c | 6 ++-- 25 files changed, 137 insertions(+), 97 deletions(-)
-- 1.7.2.3