Hi!
John Darrington <j...@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’.
