Re: [Patch v3] string-list: Document STRING_LIST_INIT_* macros.

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Sep 6, 2010, 00:22 UTC
Message-ID: <20100906002249.GB18060@burratino>
In-Reply-To: <1283731991-15080-1-git-send-email-tfransosi@gmail.com>

Thiago Farina wrote:

Show 10 quoted lines

> +++ b/Documentation/technical/api-string-list.txt
> @@ -11,10 +11,15 @@ The caller:
>  
>  . Allocates and clears a `struct string_list` variable.
>  
> -. Initializes the members. You might want to set the flag `strdup_strings`
> -  if the strings should be strdup()ed. For example, this is necessary
> -  when you add something like git_path("..."), since that function returns
> -  a static buffer that will change with the next call to git_path().
> +. Initializes the members. A string_list might be initialize by

s/initialize/initalized/, I think.

Show 7 quoted lines

> +  `= STRING_LIST_INT_NODUP` or `= STRING_LIST_INIT_DUP` before it can be used.
> +
> +  Strings in lists initialized with the _DUP variant will be
> +  automatically strdup()ed on insertion and free()ed on removal.
> +  For example, this is necessary when you add something like
> +  git_path("..."), since that function returns a static buffer
> +  that will change with the next call to git_path().

If we do not have a string_list_init() function, maybe it is worth mentioning how a person can use

 memset(&list, 0, sizeof(struct string_list));
 list.strdup_strings = 1 or 0;

too?

The previous text tried (too subtly, perhaps) to imply that with the "clears" (for memset) and "might want to set the flag `strdup_strings`" phrases.

Show 12 quoted lines

> @@ -34,10 +39,9 @@ member (you need this if you add things later) and you should set the
>  Example:
>  
>  ----
> -struct string_list list;
> +struct string_list list = STRING_LIST_DUP;
>  int i;
>  
> -memset(&list, 0, sizeof(struct string_list));
>  string_list_append(&list, "foo");
>  string_list_append(&list, "bar");
>  for (i = 0; i < list.nr; i++)

Probably worth copying and pasting this code to another file and trying it to make sure it works for the final draft.

Also, I am afraid I will not be able to send detailed reviews on uncomplicated patches like this one in the future. It simply does not scale (though I like for people to learn, at a certain point it becomes faster to do things myself).

So if you can, it is best to find ways to motivate other people to help with your work, by conveying what problems it will solve (in this case: people might be confused about the initialization sequence; as part of patch 3 demonstrated, the invariants regarding strdup_strings are not being described clearly enough) and finding ways to minimize the time other people have to spend to get it done.

Regards, Jonathan