Incorrect service documentation?

[Chris Marusich]

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

signature.asc
Description: PGP signature