Incorrect service documentation?

Incorrect service documentation?

[Chris Marusich]

[-- Attachment #1: Type: text/plain, Size: 2813 bytes --]

Hi,

The manual ((guix) Service Reference) reads:

 -- Data Type: service-type
     This is the representation of a “service type” (*note Service Types
     and Services::).

     ‘name’
          This is a symbol, used only to simplify inspection and
          debugging.

     ‘extensions’
          A non-empty list of ‘<service-extension>’ objects (see below).

     ‘compose’ (default: ‘#f’)
          If this is ‘#f’, then the service type denotes services that
          cannot be extended—i.e., services that do not receive “values”
          from other services.

          Otherwise, it must be a one-argument procedure.  The procedure
          is called by ‘fold-services’ and is passed a list of values
          collected from extensions.  It must return a value that is a
          valid parameter value for the service instance.

     ‘extend’ (default: ‘#f’)
          If this is ‘#f’, services of this type cannot be extended.

          Otherwise, it must be a two-argument procedure:
          ‘fold-services’ calls it, passing it the initial value of the
          service as the first argument and the result of applying
          ‘compose’ to the extension values as the second argument.

Is the description of "compose" correct?  The manual claims that it
"must return a value that is a valid parameter value for the service
instance," but I do not think that is actually true.  Judging by the
implementation of fold-services in (gnu services), it may return any
single value as long as the extend procedure knows how to handle it.  In
fact, it is the "extend" procedure which must return a valid parameter
value for the service.

If this is true, then I suggest we change the documentation as follows:

     ‘compose’ (default: ‘#f’)
          If this is ‘#f’, then the service type denotes services that
          cannot be extended—i.e., services that do not receive “values”
          from other services.

          Otherwise, it must be a one-argument procedure.  The procedure
          is called by ‘fold-services’ and is passed a list of values
          collected from extensions.  It may return any single value.

     ‘extend’ (default: ‘#f’)
          If this is ‘#f’, services of this type cannot be extended.

          Otherwise, it must be a two-argument procedure:
          ‘fold-services’ calls it, passing it the initial value of the
          service as the first argument and the result of applying
          ‘compose’ to the extension values as the second argument.  It
          must return a value that is a valid parameter value for the
          service instance.

What do you think?

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Incorrect service documentation?

[Ludovic Courtès]

Hello!

Chris Marusich <cmmarusich@gmail.com> skribis:

> Is the description of "compose" correct?  The manual claims that it
> "must return a value that is a valid parameter value for the service
> instance," but I do not think that is actually true.  Judging by the
> implementation of fold-services in (gnu services), it may return any
> single value as long as the extend procedure knows how to handle it.  In
> fact, it is the "extend" procedure which must return a valid parameter
> value for the service.

Yes, you’re right!  Good catch.

> If this is true, then I suggest we change the documentation as follows:
>
>      ‘compose’ (default: ‘#f’)
>           If this is ‘#f’, then the service type denotes services that
>           cannot be extended—i.e., services that do not receive “values”
>           from other services.
>
>           Otherwise, it must be a one-argument procedure.  The procedure
>           is called by ‘fold-services’ and is passed a list of values
>           collected from extensions.  It may return any single value.
>
>      ‘extend’ (default: ‘#f’)
>           If this is ‘#f’, services of this type cannot be extended.
>
>           Otherwise, it must be a two-argument procedure:
>           ‘fold-services’ calls it, passing it the initial value of the
>           service as the first argument and the result of applying
>           ‘compose’ to the extension values as the second argument.  It
>           must return a value that is a valid parameter value for the
>           service instance.
>
> What do you think?

LGTM!

Thank you,
Ludo’.

Re: Incorrect service documentation?

[Chris Marusich]

[-- Attachment #1: Type: text/plain, Size: 1867 bytes --]

ludo@gnu.org (Ludovic Courtès) writes:

> Hello!
>
> Chris Marusich <cmmarusich@gmail.com> skribis:
>
>> Is the description of "compose" correct?  The manual claims that it
>> "must return a value that is a valid parameter value for the service
>> instance," but I do not think that is actually true.  Judging by the
>> implementation of fold-services in (gnu services), it may return any
>> single value as long as the extend procedure knows how to handle it.  In
>> fact, it is the "extend" procedure which must return a valid parameter
>> value for the service.
>
> Yes, you’re right!  Good catch.

Thank you for confirming my understanding!

>> If this is true, then I suggest we change the documentation as follows:
>>
>>      ‘compose’ (default: ‘#f’)
>>           If this is ‘#f’, then the service type denotes services that
>>           cannot be extended—i.e., services that do not receive “values”
>>           from other services.
>>
>>           Otherwise, it must be a one-argument procedure.  The procedure
>>           is called by ‘fold-services’ and is passed a list of values
>>           collected from extensions.  It may return any single value.
>>
>>      ‘extend’ (default: ‘#f’)
>>           If this is ‘#f’, services of this type cannot be extended.
>>
>>           Otherwise, it must be a two-argument procedure:
>>           ‘fold-services’ calls it, passing it the initial value of the
>>           service as the first argument and the result of applying
>>           ‘compose’ to the extension values as the second argument.  It
>>           must return a value that is a valid parameter value for the
>>           service instance.
>>
>> What do you think?
>
> LGTM!

I've committed this as 881c61d06222a30dbffbf9d039eaca2abd3d22b3.

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]