From 7575e119d68a415a4be62966acbd8970094d7b3e Mon Sep 17 00:00:00 2001
From: Alex Brandt <alunduil@gmail.com>
Date: Wed, 17 Oct 2018 21:30:36 -0700
Subject: [PATCH] systemd: add more detail to user unit documentation

The current documentation does not provide guidance to users on how
systemd units are defined in Home Manager. A user may expect the
configuration to be similar to NixOS, when it actually differs.

Fixes #418
---
 modules/systemd.nix | 54 ++++++++++++++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 20 deletions(-)

diff --git a/modules/systemd.nix b/modules/systemd.nix
index 74490691..ed630b36 100644
--- a/modules/systemd.nix
+++ b/modules/systemd.nix
@@ -55,6 +55,30 @@ let
     merge = loc: foldl' (res: def: recursiveUpdate res def.value) {};
   };
 
+  unitDescription = type: ''
+    Definition of systemd per-user ${type} units. Attributes are
+    merged recursively.
+    </para><para>
+    Note that the attributes follow the capitalization and naming used
+    by systemd. More details can be found in
+    <citerefentry>
+      <refentrytitle>systemd.${type}</refentrytitle>
+      <manvolnum>5</manvolnum>
+    </citerefentry>.
+  '';
+
+  unitExample = type: literalExample ''
+    {
+      Unit = {
+        Description = "Example description";
+      };
+
+      ${type} = {
+        …
+      };
+    }
+  '';
+
 in
 
 {
@@ -76,46 +100,36 @@ in
       services = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
-          Definition of systemd per-user service units. Attributes are
-          merged recursively.
-        '';
+        description = unitDescription "service";
+        example = unitExample "Service";
       };
 
       sockets = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
-          Definition of systemd per-user sockets. Attributes are
-          merged recursively.
-        '';
+        description = unitDescription "socket";
+        example = unitExample "Socket";
       };
 
       targets = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
-          Definition of systemd per-user targets. Attributes are
-          merged recursively.
-        '';
+        description = unitDescription "target";
+        example = unitExample "Target";
       };
 
       timers = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
-          Definition of systemd per-user timers. Attributes are merged
-          recursively.
-        '';
+        description = unitDescription "timer";
+        example = unitExample "Timer";
       };
 
       paths = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
-          Definition of systemd per-user path units. Attributes are
-          merged recursively.
-        '';
+        description = unitDescription "path";
+        example = unitExample "Path";
       };
 
       startServices = mkOption {