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

@@ -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 = ''
+        description = unitDescription "service";
-          Definition of systemd per-user service units. Attributes are
+        example = unitExample "Service";
-          merged recursively.
-        '';
       };
 
       sockets = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
+        description = unitDescription "socket";
-          Definition of systemd per-user sockets. Attributes are
+        example = unitExample "Socket";
-          merged recursively.
-        '';
       };
 
       targets = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
+        description = unitDescription "target";
-          Definition of systemd per-user targets. Attributes are
+        example = unitExample "Target";
-          merged recursively.
-        '';
       };
 
       timers = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
+        description = unitDescription "timer";
-          Definition of systemd per-user timers. Attributes are merged
+        example = unitExample "Timer";
-          recursively.
-        '';
       };
 
       paths = mkOption {
         default = {};
         type = attrsRecursivelyMerged;
-        description = ''
+        description = unitDescription "path";
-          Definition of systemd per-user path units. Attributes are
+        example = unitExample "Path";
-          merged recursively.
-        '';
       };
 
       startServices = mkOption {