Re: [PATCH] gnu: Add rpc-daemon service

[ludo@gnu.org (Ludovic Courtès)]

Hi!

John Darrington <jmd@gnu.org> 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.

[...]

> +@subsubheading RPC Bind Service
> +@cindex rpcbind
> +
> +The @code{(gnu services nfs)} module provides the following:
> +
> +@defvr {Scheme Variable} rpcbind-service-type
> +A service type  for the RPC portmapper daemon.
> +@end defvr
> +
> +
> +@deftp {Data Type} rpcbind-configuration
> +Data type representing the configuration of the RPC Bind Service.
> +This type has the following parameters:
> +@table @asis
> +@item @code{rpcbind} (default: @code{rpcbind})
> +The rpcbind package to use.
> +
> +@item @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’.