8 files changed, 48 insertions(+), 13 deletions(-)

M gnu/services/dbus.scm
M gnu/services/dict.scm
M gnu/services/dns.scm
M gnu/services/networking.scm
M gnu/services/shepherd.scm
M gnu/services/xorg.scm
M gnu/system/pam.scm
M gnu/system/shadow.scm

@@ 1,5 1,5 @@
 ;;; GNU Guix --- Functional package management for GNU
-;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2019 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2019, 2020 Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright © 2015 Sou Bunnbu <iyzsong@gmail.com>
 ;;;
 ;;; This file is part of GNU Guix.


@@ 363,7 363,13 @@ tuples, are all set as environment variables when the bus daemon launches it."
                             (append (polkit-configuration-actions config)
                                     actions)))))
 
-                (default-value (polkit-configuration))))
+                (default-value (polkit-configuration))
+                (description
+                 "Run the
+@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
+management service}, which allows system administrators to grant access to
+privileged operations in a structured way.  Polkit is a requirement for most
+desktop environments, such as GNOME.")))
 
 (define* (polkit-service #:key (polkit polkit))
   "Return a service that runs the

@@ 1,6 1,6 @@
 ;;; GNU Guix --- Functional package management for GNU
 ;;; Copyright © 2016 Sou Bunnbu <iyzsong@gmail.com>
-;;; Copyright © 2016, 2017, 2018 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2016, 2017, 2018, 2020 Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright © 2017 Huang Ying <huang.ying.caritas@gmail.com>
 ;;;
 ;;; This file is part of GNU Guix.


@@ 174,7 174,12 @@ database {
                              (const %dicod-activation))
           (service-extension shepherd-root-service-type
                              dicod-shepherd-service)))
-   (default-value (dicod-configuration))))
+   (default-value (dicod-configuration))
+   (description
+    "Run @command{dicod}, the dictionary server of
+@uref{https://www.gnu.org/software/dico, GNU Dico}.  @command{dicod}
+implements the standard DICT protocol supported by clients such as
+@command{dico} and GNOME Dictionary.")))
 
 (define* (dicod-service #:key (config (dicod-configuration)))
   "Return a service that runs the @command{dicod} daemon, an implementation

@@ 639,7 639,10 @@
                         (service-extension activation-service-type
                                            knot-activation)
                         (service-extension account-service-type
-                                           (const %knot-accounts))))))
+                                           (const %knot-accounts))))
+                (description
+                 "Run @uref{https://www.knot-dns.cz/, Knot}, an authoritative
+name server for the @acronym{DNS, Domain Name System}.")))
 
 
 ;;;

@@ 335,7 335,9 @@ Protocol (DHCP) client, on all the non-loopback network interfaces."
    (name 'dhcpd)
    (extensions
     (list (service-extension shepherd-root-service-type dhcpd-shepherd-service)
-          (service-extension activation-service-type dhcpd-activation)))))
+          (service-extension activation-service-type dhcpd-activation)))
+   (description "Run a DHCP (Dynamic Host Configuration Protocol) daemon.  The
+daemon is responsible for allocating IP addresses to its client.")))
 
 
 ;;;

@@ 105,7 105,11 @@
    (extensions (list (service-extension boot-service-type
                                         shepherd-boot-gexp)
                      (service-extension profile-service-type
-                                        (const (list shepherd)))))))
+                                        (const (list shepherd)))))
+   (description
+    "Run the GNU Shepherd as PID 1---i.e., the operating system's first
+process.  The Shepherd takes care of managing services such as daemons by
+ensuring they are started and stopped in the right order.")))
 
 (define %shepherd-root-service
   ;; The root shepherd service, aka. PID 1.  Its parameter is a list of

@@ 1,6 1,6 @@
 ;;; GNU Guix --- Functional package management for GNU
 ;;; Copyright © 2017 Andy Wingo <wingo@igalia.com>
-;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2019 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2019, 2020 Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright © 2015 Sou Bunnbu <iyzsong@gmail.com>
 ;;; Copyright © 2018, 2019 Timothy Sample <samplet@ngyro.com>
 ;;; Copyright © 2019 Jan (janneke) Nieuwenhuizen <janneke@gnu.org>


@@ 619,7 619,9 @@ reboot_cmd " shepherd "/sbin/reboot\n"
                          (service-extension profile-service-type
                                             (const (list xterm)))))
 
-                  (default-value (slim-configuration)))))
+                  (default-value (slim-configuration))
+                  (description
+                   "Run the SLiM graphical login manager for X11."))))
 
 (define-deprecated (slim-service #:key (slim slim)
                                  (allow-empty-passwords? #t) auto-login?


@@ 691,7 693,11 @@ theme."
                  (list (service-extension pam-root-service-type
                                           screen-locker-pam-services)
                        (service-extension setuid-program-service-type
-                                          screen-locker-setuid-programs)))))
+                                          screen-locker-setuid-programs)))
+                (description
+                 "Allow the given program to be used as a screen locker for
+the graphical server by making it setuid-root, so it can authenticate users,
+and by creating a PAM service for it.")))
 
 (define* (screen-locker-service package
                                 #:optional

@@ 1,5 1,5 @@
 ;;; GNU Guix --- Functional package management for GNU
-;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2019 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2019, 2020 Ludovic Courtès <ludo@gnu.org>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;


@@ 367,7 367,13 @@ strings or string-valued gexps."
 
                 ;; Arguments include <pam-service> as well as procedures.
                 (compose concatenate)
-                (extend extend-configuration)))
+                (extend extend-configuration)
+                (description
+                 "Configure the Pluggable Authentication Modules (PAM) for all
+the specified @dfn{PAM services}.  Each PAM service corresponds to a program,
+such as @command{login} or @command{sshd}, and specifies for instance how the
+program may authenticate users or what it should do when opening a new
+session.")))
 
 (define* (pam-root-service base #:key (transform identity))
   "The \"root\" PAM service, which collects <pam-service> instance and turns

@@ 378,7 378,10 @@ the /etc/skel directory for those."
                        (service-extension user-processes-service-type
                                           (const '(user-homes)))
                        (service-extension etc-service-type
-                                          etc-files)))))
+                                          etc-files)))
+                (description
+                 "Ensure the specified user accounts and groups exist, as well
+as each account home directory.")))
 
 (define (account-service accounts+groups skeletons)
   "Return a <service> that takes care of user accounts and user groups, with