12/15: doc: Further clarify documentation of 'host' and 'hosts-service-type'.

[guix-commits]

civodul pushed a commit to branch master
in repository guix.

commit 810788b5509cf4ab7c2d6b70c0a416880301d837
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Thu Feb 23 16:15:49 2023 +0100

    doc: Further clarify documentation of 'host' and 'hosts-service-type'.
    
    * doc/guix.texi (Base Services): Use docstring of 'host' to document
    it and remove @deftp.  Introduce example.  Fix typos in file name.
---
 doc/guix.texi | 30 +++++++++++-------------------
 1 file changed, 11 insertions(+), 19 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index fa4d94c1d7..73ebbfa8f4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18025,6 +18025,8 @@ Type of the service that populates the entries for 
(@file{/etc/hosts}).
 This service type can be @emph{extended} by passing it a list of
 @code{host} records.
 
+The example below shows how to add two entries to @file{/etc/hosts}:
+
 @c TRANSLATORS: The domain names below SHOULD NOT be translated.
 @c They're domains reserved for use in documentation. (RFC6761 Section 6.5)
 @c The addresses used are explained in RFC3849 and RFC5737.
@@ -18038,8 +18040,8 @@ This service type can be @emph{extended} by passing it 
a list of
 @end lisp
 
 @quotation Note
-@cindex @file{/etc/host} default entries
-By default @file{/etc/host} comes with the following entries:
+@cindex @file{/etc/hosts} default entries
+By default @file{/etc/hosts} comes with the following entries:
 @example
 127.0.0.1 localhost @var{host-name}
 ::1       localhost @var{host-name}
@@ -18064,27 +18066,17 @@ alias of @code{localhost}.
                                      (host "::1"       "localhost"))))))
 @end lisp
 @end quotation
+@end defvar
 
-@deftp {Data Type} host
-Available @code{host} fields are:
-
-@table @asis
-@item @code{address} (type: string)
-IP address.
-
-@item @code{canonical-name} (type: string)
-Hostname.
-
-@item @code{aliases} (default: @code{'()}) (type: list-of-string)
-Additional aliases that map to the same @code{canonical-name}.
 
-@end table
-@end deftp
+@defun host @var{address} @var{canonical-name} [@var{aliases}]
+Return a new record for the host at @var{address} with the given
+@var{canonical-name} and possibly @var{aliases}.
 
-@defun host address canonical-name [aliases]
-Procedure for creating @code{host} records.
+@var{address} must be a string denoting a valid IPv4 or IPv6 address, and
+@var{canonical-name} and the strings listed in @var{aliases} must be valid
+host names.
 @end defun
-@end defvar
 
 @deffn {Scheme Procedure} login-service @var{config}
 Return a service to run login according to @var{config}, a