[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] gnu: Add rpc-daemon service
From: |
Ludovic Courtès |
Subject: |
Re: [PATCH] gnu: Add rpc-daemon service |
Date: |
Wed, 07 Sep 2016 14:17:48 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.5 (gnu/linux) |
Hi!
John Darrington <address@hidden> skribis:
> If I might be allowed to give my opinion though ... I think this way of
> documenting
> things is of limited help to potential users. It does nothing more than
> repeat what
> is written in the code. If that is what we want, then we could use some kind
> of
> literate programming tool to do it. That would be less maintenence and avoids
> the possibility of code and documentation becoming out of sync.
I don’t see anything in nfs.scm explaining, for instance, the
‘warm-start?’ knob; nor is anything (and rightfully so) hinting at what
NFS is and how rpcbind relates to it.
> However, what is really needed from documentation IMO, is not only a API
> reference,
> but also a tutorial on how to use the thing. I think this form of
> documentation will only
> leave the newcommer scratching his head.
I agree. It’s often a good idea to (1) give context and relevant
cross-references in the doc, and (2) include an example for non-trivial
services. For instance, I think the “Desktop Services” and “Scheduled
Job Execution” sections are doing pretty good in this regard.
> * gnu/services/nfs.scm: New file.
> * gnu/local.mk (GNU_SYSTEM_MODULES): Add it.
[...]
> address@hidden RPC Bind Service
> address@hidden rpcbind
> +
> +The @code{(gnu services nfs)} module provides the following:
> +
> address@hidden {Scheme Variable} rpcbind-service-type
> +A service type for the RPC portmapper daemon.
> address@hidden defvr
> +
> +
> address@hidden {Data Type} rpcbind-configuration
> +Data type representing the configuration of the RPC Bind Service.
> +This type has the following parameters:
> address@hidden @asis
> address@hidden @code{rpcbind} (default: @code{rpcbind})
> +The rpcbind package to use.
> +
> address@hidden @code{warm-start?}
^
Mention the default value here…
> +If this parameter is @code{#t} (the default), then the daemon will read a
^
… and not here.
Other than that, LGTM!
Regarding documentation, since you asked ;-), what could work well here
is to have a complete “Network File System” @subsection. It would start
with a short intro of what NFS is, provide an example showing how to
export a directory over NFS, give an overview of the services involved
(rpcbind, mountd, statd), and then give the API reference.
Thoughts for future work. :-)
Thank you!
Ludo’.