Re: [PATCH] api-credential.txt: document that helpers field is filled-in automatically

From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Jun 12, 2012, 09:39 UTC
Message-ID: <vpq7gvcx40y.fsf@bauges.imag.fr>
In-Reply-To: <20120611190811.GB20889@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 18 quoted lines

> On Mon, Jun 11, 2012 at 07:51:47PM +0200, Matthieu Moy wrote:
>
>> It was unclear whether the field was to be specified by the user of the
>> API.
>> 
>> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
>> ---
>> > It is correct that the C API asks helpers that the user configured,
>> > but I think it is common across three API functions, not limited to
>> > credential_fill().  credential_apply_config() is called from approve
>> > and reject, too.
>> 
>> Ah, right, so compared to v1, we can move the sentence to the
>> description of the "helpers" field, like this:
>
> I think this is OK. Technically it loads other matching config, as well
> (filling in default username fields and respecting useHttpPath). I don't
> know if it is worth mentioning them, too.

Probably not, but I don't care much here. The "helpers" field was particular in that by reading the documentation, I first thought that the caller may have a reason to fill-in this field.

Show 7 quoted lines

>> -helpers below.
>> +helpers below. This list is filled-in by the API functions
>> +according to the corresponding configuration variables before
>> +consulting helpers.
>
> You might want to say something like "...and therefore there is usually
> no need for a caller to modify the helpers field at all".

Agreed. I see that Junio already has this fixup in pu. Junio, let me know if you prefer a resend.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/