[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Incorrect service documentation?
From: |
Chris Marusich |
Subject: |
Incorrect service documentation? |
Date: |
Fri, 23 Mar 2018 11:09:34 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.3 (gnu/linux) |
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
- Incorrect service documentation?,
Chris Marusich <=