From: Thiago Farina <tfransosi@gmail.com>
Date: Sun, 05 Sep 2010 23:19:15 GMT
Subject: Re: [demo/patch 0/3] Re: [PATCH] Documentation: document the string-list macros.
Message-ID: <AANLkTinP1XNsVCnyL+dnn_+up1Oi6aSxiaA_JjdKDGje@mail.gmail.com>
In-Reply-To: <20100905200323.GA14497@burratino>

On Sun, Sep 5, 2010 at 5:03 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Thiago Farina wrote:
>
>> --- 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.
>
Yeah, you are right.

> 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.
>
I have looked into it :-)

> Maybe something in this direction?
>
> Patch #3 in particular is very rough
Oh yeah :)

>  This is not meant for application, just to give an
> idea.
>
I like the idea. I will improve the Documentation based on or version.

Thanks.