Document pleroma module and options

shared/pleroma/default.nix

@@ -1,3 +1,14 @@
+# [Pleroma][] is a fediverese server.
+#
+# Pleroma uses a containerised postgres database.
+#
+# If the `backups` module is enabled, adds a script to backup the database and
+# uploaded files.
+#
+# If the `erase-your-darlings` module is enabled, stores its data on the
+# persistent volume.
+#
+# [Pleroma]: https://pleroma.social/
 { config, lib, pkgs, ... }:
 
 with lib;

shared/pleroma/options.nix

@@ -4,15 +4,86 @@ with lib;
 
 {
   options.nixfiles.pleroma = {
-    enable = mkOption { type = types.bool; default = false; };
-    port = mkOption { type = types.int; default = 46283; };
-    pgTag = mkOption { type = types.str; default = "13"; };
-    domain = mkOption { type = types.str; };
-    faviconPath = mkOption { type = types.nullOr types.path; default = null; };
-    instanceName = mkOption { type = types.nullOr types.str; default = null; };
-    adminEmail = mkOption { type = types.str; default = "[email protected]"; };
-    notifyEmail = mkOption { type = types.nullOr types.str; default = null; };
-    allowRegistration = mkOption { type = types.bool; default = false; };
-    secretsFile = mkOption { type = types.str; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the `pleroma` service.
+      '';
+    };
+
+    port = mkOption {
+      type = types.int;
+      default = 46283;
+      description = mdDoc ''
+        Port (on 127.0.0.1) to expose the pleroma service on.
+      '';
+    };
+
+    pgTag = mkOption {
+      type = types.str;
+      default = "13";
+      description = mdDoc ''
+        Tag to use of the `postgres` container image.
+      '';
+    };
+
+    domain = mkOption {
+      type = types.str;
+      example = "social.lainon.life";
+      description = mdDoc ''
+        Domain which the service will be exposed on.
+      '';
+    };
+
+    faviconPath = mkOption {
+      type = types.nullOr types.path;
+      default = null;
+      description = mdDoc ''
+        Path to the favicon file.
+      '';
+    };
+
+    instanceName = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = mdDoc ''
+        Name of the instance, defaults to the `''${domain}` if not set.
+      '';
+    };
+
+    adminEmail = mkOption {
+      type = types.str;
+      default = "[email protected]";
+      description = mdDoc ''
+        Email address used to contact the server operator.
+      '';
+    };
+
+    notifyEmail = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = mdDoc ''
+        Email address used for notification, defaults to the `''${adminEmail}`
+        if not set.
+      '';
+    };
+
+    allowRegistration = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Whether to allow new users to sign up.
+      '';
+    };
+
+    secretsFile = mkOption {
+      type = types.str;
+      description = mdDoc ''
+        Path to the secret configuration file.
+
+        See the Pleroma documentation for what this needs to contain.
+      '';
+    };
   };
 }