From 4325768477d9eb5ee543614d5fa47976ebb1481e Mon Sep 17 00:00:00 2001
From: Michael Walker <mike@barrucadu.co.uk>
Date: Sun, 15 Oct 2023 21:37:12 +0100
Subject: [PATCH] Document `finder` module and options

---
 shared/finder/default.nix |  8 ++++++++
 shared/finder/options.nix | 43 ++++++++++++++++++++++++++++++++++-----
 2 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/shared/finder/default.nix b/shared/finder/default.nix
index ba85389d..05a94722 100644
--- a/shared/finder/default.nix
+++ b/shared/finder/default.nix
@@ -1,3 +1,11 @@
+# Webapp to read downloaded manga.  There is no public deployment.
+#
+# finder uses a containerised elasticsearch database, and requires read access
+# to the filesystem where manga is stored.  It does not manage the manga, only
+# provides an interface to search and read.
+#
+# The database can be recreated from the manga files, so this module does not
+# include a backup script.
 { config, lib, ... }:
 
 with lib;
diff --git a/shared/finder/options.nix b/shared/finder/options.nix
index 8dc07a2e..51dece27 100644
--- a/shared/finder/options.nix
+++ b/shared/finder/options.nix
@@ -4,10 +4,43 @@ with lib;
 
 {
   options.nixfiles.finder = {
-    enable = mkOption { type = types.bool; default = false; };
-    image = mkOption { type = types.str; };
-    port = mkOption { type = types.int; default = 44986; };
-    esTag = mkOption { type = types.str; default = "8.0.0"; };
-    mangaDir = mkOption { type = types.path; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the `finder` module.
+      '';
+    };
+
+    image = mkOption {
+      type = types.str;
+      description = mdDoc ''
+        Container image to use.
+      '';
+    };
+
+    port = mkOption {
+      type = types.int;
+      default = 44986;
+      description = mdDoc ''
+        Port (on 127.0.0.1) to expose the finder service on.
+      '';
+    };
+
+    esTag = mkOption {
+      type = types.str;
+      default = "8.0.0";
+      description = mdDoc ''
+        Tag to use of the `elasticsearch` container image.
+      '';
+    };
+
+    mangaDir = mkOption {
+      type = types.path;
+      example = "/mnt/nas/manga";
+      description = mdDoc ''
+        Directory to serve manga files from.
+      '';
+    };
   };
 }