From e78cb05954d693efa9c4f19069464f54b83ad8ce Mon Sep 17 00:00:00 2001
From: Michael Walker <mike@barrucadu.co.uk>
Date: Sun, 15 Oct 2023 16:15:54 +0100
Subject: [PATCH] Document `bookmarks` module and options

---
 shared/bookmarks/default.nix | 11 +++++++
 shared/bookmarks/options.nix | 64 ++++++++++++++++++++++++++++++++----
 2 files changed, 68 insertions(+), 7 deletions(-)

diff --git a/shared/bookmarks/default.nix b/shared/bookmarks/default.nix
index ffad848b..11b1cebb 100644
--- a/shared/bookmarks/default.nix
+++ b/shared/bookmarks/default.nix
@@ -1,3 +1,14 @@
+# Webapp to keep track of all my bookmarks, deployed to
+# [bookmarks.barrucadu.co.uk][].
+#
+# bookmarks uses a containerised elasticsearch database.
+#
+# If the `backups` module is enabled, adds a script to backup the database.
+#
+# If the `erase-your-darlings` module is enabled, stores its data on the
+# persistent volume.
+#
+# [bookmarks.barrucadu.co.uk]: https://bookmarks.barrucadu.co.uk/
 { config, lib, pkgs, ... }:
 
 with lib;
diff --git a/shared/bookmarks/options.nix b/shared/bookmarks/options.nix
index 670bb2d5..49f33969 100644
--- a/shared/bookmarks/options.nix
+++ b/shared/bookmarks/options.nix
@@ -4,12 +4,62 @@ with lib;
 
 {
   options.nixfiles.bookmarks = {
-    enable = mkOption { type = types.bool; default = false; };
-    port = mkOption { type = types.int; default = 48372; };
-    esPort = mkOption { type = types.int; default = 43389; };
-    esTag = mkOption { type = types.str; default = "8.0.0"; };
-    baseURI = mkOption { type = types.str; };
-    readOnly = mkOption { type = types.bool; default = false; };
-    environmentFile = mkOption { type = types.nullOr types.str; default = null; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the `bookmarks` module.
+      '';
+    };
+
+    port = mkOption {
+      type = types.int;
+      default = 48372;
+      description = mdDoc ''
+        Port (on 127.0.0.1) to expose the bookmarks service on.
+      '';
+    };
+
+    esPort = mkOption {
+      type = types.int;
+      default = 43389;
+      description = mdDoc ''
+        Port (on 127.0.0.1) to expose the elasticsearch container on.
+      '';
+    };
+
+    esTag = mkOption {
+      type = types.str;
+      default = "8.0.0";
+      description = mdDoc ''
+        Tag to use of the `elasticsearch` container image.
+      '';
+    };
+
+    baseURI = mkOption {
+      type = types.str;
+      example = "https://bookmarks.barrucadu.co.uk";
+      description = mdDoc ''
+        URI which the service will be exposed on, used to generate URLs.
+      '';
+    };
+
+    readOnly = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Whether to launch the service in "read-only" mode.  Enable this if
+        exposing it to a public network.
+      '';
+    };
+
+    environmentFile = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = mdDoc ''
+        Environment file to be passed to the systemd services.  This needs to
+        contain a `YOUTUBE_API_KEY` if not running in read-only mode.
+      '';
+    };
   };
 }