queue.scm: Add docstrings to Dovecot variables, and mark it as finished

1 files changed, 34 insertions, 16 deletions

diff --git a/src/org/euandre/queue.scm b/src/org/euandre/queue.scm
index 55444b0..e551784 100644
--- a/src/org/euandre/queue.scm
+++ b/src/org/euandre/queue.scm
@@ -619,7 +619,7 @@ to the list of supplementary groups of the user of such running process.")))
                                 (file-system-mapping
                                   (source "/etc/shadow")
                                   (target source)))
-                                extra-mappings)))))
+                               extra-mappings)))))
       (list
        (shepherd-service
          (provision '(cyrus-sasl))
@@ -1145,7 +1145,7 @@ header_checks = regexp:{ { /^Received:.*/ IGNORE }, { /^X-Originating-IP:.*/ IGN
                                   (source queue-directory)
                                   (target source)
                                   (writable? #t)))
-                                extra-mappings)))))
+                               extra-mappings)))))
       (list
        (shepherd-service
          (provision '(postfix))
@@ -1163,8 +1163,7 @@ commands.")
            (list
             (shepherd-action
               (name 'configuration)
-              (documentation "Display the name of the \"master.cf\" and
-\"main.cf\" file being used")
+              (documentation "Display the name of the \"master.cf\" and \"main.cf\" file being used.")
               (procedure
                 #~(lambda _
                     (format #t "~a/master.cf~%" #$config-dir)
@@ -1273,7 +1272,7 @@ An extension to the log-rotation service isn't included: the default rottlog
 configuration already includes @file{/var/log/maillog} in its routine, so it is
 kept out.
 
-The defaults of @code{<postfix-configuration>} provide sane default values for
+The defaults of @code{<postfix-configuration>} provides sane default values for
 most things, such as group names, data and queue directories, etc.  When used
 as-is, it creates a Postfix server that sends email locally-only, and one can
 add relaying configuration via the @code{main.cf-extra} parameter.")))
@@ -1314,19 +1313,13 @@ It includes everything from @code{local-postfix-service-type}, plus:
       @code{saslauthd} daemon.
 @end itemize
 
-The defaults of @code{<postfix-configuration>} provide sane default values for
+The defaults of @code{<postfix-configuration>} provides sane default values for
 most things, hostname, certificates, permissions, etc.  When used as-is, it
 creates a Postfix server that can send and receive emails from the internet
 correctly.")))
 
 
 
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; WIP services ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
-
-
-
 (define-record-type* <dovecot-configuration>
   dovecot-configuration
   make-dovecot-configuration
@@ -1514,7 +1507,7 @@ namespace inbox {
       (list
        (shepherd-service
          (provision '(dovecot))
-         (documentation "")
+         (documentation "Run the Dovecot daemon.")
          (start #~(make-forkexec-constructor
                    (list #$cmd "-F" "-c" #$config-file)))
          (stop #~(make-kill-destructor))
@@ -1522,13 +1515,13 @@ namespace inbox {
            (list
             (shepherd-action
               (name 'configuration)
-              (documentation "FIXME:DOCUMENTATION: heredoc syntax")
+              (documentation "Display the name of the configuration file being used.")
               (procedure
                 #~(lambda _
                     (format #t "~a~%" #$config-file))))
             (shepherd-action
               (name 'reload)
-              (documentation "FIXME:DOCUMENTATION: heredoc syntax")
+              (documentation "Re-read the configuration file without restarting the running dovecot daemon.")
               (procedure
                 #~(lambda _
                     (invoke #$(file-append package "/bin/doveadm")
@@ -1552,7 +1545,32 @@ namespace inbox {
        (service-extension shepherd-root-service-type
                           dovecot-shepherd-service)))
     (default-value (dovecot-configuration))
-    (description "")))
+    (description "Run the Dovecot IMAP @code{dovecot} daemon.
+
+This is the top-level system service for Dovecot, using the UNIX password stored
+at @file{/etc/shadow} for authenticating IMAP connections.
+
+It includes:
+@itemize
+@item creating the configuration file at @file{/etc/dovecot/dovecot.conf} by
+      default;
+@item the user and groups used by Dovecot both system and untrusted users;
+@item the activation script for creating the required directories and the
+      @file{dhparam.pem} file if it is missing;
+@item the Shepherd service for starting, stopping and @emph{reloading} the
+      service without restarting it;
+@item the binaries in the system profile so that one doesn't need to explicilty
+      include the package when the service is already enabled.
+@end itemize
+
+An extension to the log-rotation service isn't included: the default rottlog
+configuration already includes @file{/var/log/maillog} in its routine, so it is
+kept out.
+
+The defaults of @code{<dovecot-configuration>} provides sane default values for
+most things, such as group names, data and mail directories, etc.  When used
+as-is, it creates a Dovecot server that and serve and authenticate IMAP
+connections correctly.")))
 
 
 (define cgit-pre-configuration