Document rtorrent module and options

barrucadu · Oct 15, 2023 · 0363d34 · 0363d34
1 parent 37de90f
commit 0363d34
Show file tree

Hide file tree

Showing 2 changed files with 87 additions and 10 deletions.
diff --git a/shared/rtorrent/default.nix b/shared/rtorrent/default.nix
@@ -1,3 +1,13 @@
+# [rTorrent][] is a bittorrent client.  This module configures it in a way
+# appropriate for private trackers.
+#
+# This module does not include a backup script.  Torrented files must be backed
+# up independently.
+#
+# If the `erase-your-darlings` module is enabled, stores the session data and
+# logs on the persistent volume.
+#
+# [rTorrent]: https://github.com/rakshasa/rtorrent
 { config, lib, pkgs, ... }:
 
 with lib;

diff --git a/shared/rtorrent/options.nix b/shared/rtorrent/options.nix
@@ -4,19 +4,86 @@ with lib;
 
 {
   options.nixfiles.rtorrent = {
-    enable = mkOption { type = types.bool; default = false; };
-    downloadDir = mkOption { type = types.str; };
-    watchDir = mkOption { type = types.str; };
-    user = mkOption { type = types.str; };
-    logLevels = mkOption { type = types.listOf types.str; default = [ "info" ]; };
-    openFirewall = mkOption { type = types.bool; default = true; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the `rtorrent` service.
+      '';
+    };
+
+    downloadDir = mkOption {
+      type = types.str;
+      example = "/mnt/nas/torrents/files/";
+      description = mdDoc ''
+        Directory to download torrented files to.
+      '';
+    };
+
+    watchDir = mkOption {
+      type = types.str;
+      example = "/mnt/nas/torrents/watch/";
+      description = mdDoc ''
+        Directory to monitor for new .torrent files.
+      '';
+    };
+
+    user = mkOption {
+      type = types.str;
+      description = mdDoc ''
+        The user to run rTorrent as.
+      '';
+    };
+
+    logLevels = mkOption {
+      type = types.listOf types.str;
+      default = [ "info" ];
+      description = mdDoc ''
+        Verbosity of the log messages.
+      '';
+    };
+
+    openFirewall = mkOption {
+      type = types.bool;
+      default = true;
+      description = mdDoc ''
+        Allow connections from TCP and UDP ports `''${portRange.from}` to
+        `''${portRange.to}`.
+      '';
+    };
+
     portRange = {
-      from = mkOption { type = types.int; default = 50000; };
-      to = mkOption { type = types.int; default = 50000; };
+      from = mkOption {
+        type = types.int;
+        default = 50000;
+        description = mdDoc ''
+          Lower bound (inclusive) of the port range to accept connections on.
+        '';
+      };
+      to = mkOption {
+        type = types.int;
+        default = 50000;
+        description = mdDoc ''
+          Upper bound (inclusive) of the port range to accept connections on.
+        '';
+      };
     };
+
     flood = {
-      enable = mkOption { type = types.bool; default = true; };
-      port = mkOption { type = types.int; default = 45904; };
+      enable = mkOption {
+        type = types.bool;
+        default = true;
+        description = mdDoc ''
+          Enable the [flood](https://flood.js.org/) web UI.
+        '';
+      };
+      port = mkOption {
+        type = types.int;
+        default = 45904;
+        description = mdDoc ''
+          Port (on 127.0.0.1) to expose the flood service on.
+        '';
+      };
     };
   };
 }