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

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

[Thiago Farina]

Clarify the modern ways to initialize a string_list. Text roughly
based on the analogous passage from api-strbuf.txt.

(Note: Based on the demo patch of Jonathan Nieder).

Signed-off-by: Thiago Farina <tfransosi@gmail.com>
---
 Documentation/technical/api-string-list.txt |   16 ++++++++++------
 1 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt
index 3f575bd..f689163 100644
--- a/Documentation/technical/api-string-list.txt
+++ 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
+  `= 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 you need something advanced, you can manually malloc() the `items`
 member (you need this if you add things later) and you should set the
@@ -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++)
-- 
1.7.2.3.313.gcd15

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

[Jonathan Nieder]

Thiago Farina wrote:

> +++ 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.

> +  `= 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.

> @@ -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

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

[Thiago Farina]

On Sun, Sep 5, 2010 at 9:22 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
>> @@ -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.

I already done in the test-string-list.c patch I sent. :-)