From 0363d34fc4d5a0cbc18a689d6023273d6d2bd361 Mon Sep 17 00:00:00 2001
From: Michael Walker <mike@barrucadu.co.uk>
Date: Sun, 15 Oct 2023 23:29:51 +0100
Subject: [PATCH] Document `rtorrent` module and options

---
 shared/rtorrent/default.nix | 10 +++++
 shared/rtorrent/options.nix | 87 ++++++++++++++++++++++++++++++++-----
 2 files changed, 87 insertions(+), 10 deletions(-)

diff --git a/shared/rtorrent/default.nix b/shared/rtorrent/default.nix
index a59a7443..afa907e7 100644
--- 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
index f17c4725..1cc1ed40 100644
--- 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.
+        '';
+      };
     };
   };
 }