From 33d449b977c83562a26e0fdf583a67fba9cac7c2 Mon Sep 17 00:00:00 2001
From: Kiara Grouwstra <kiara@procolix.eu>
Date: Thu, 18 Sep 2025 11:25:02 +0200
Subject: [PATCH] better document function.nix

Signed-off-by: Kiara Grouwstra <kiara@procolix.eu>
---
 deployment/function.nix | 35 ++++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/deployment/function.nix b/deployment/function.nix
index 76795e68..63533fdc 100644
--- a/deployment/function.nix
+++ b/deployment/function.nix
@@ -1,5 +1,38 @@
 /**
-  Modular function type
+  Modular function type.
+
+  Compared to plain nix functions, adds input type-checks
+  at the cost of longer stack traces.
+
+  Usage:
+
+  ```nix
+  { lib, ... }:
+  {
+    options = {
+      my-function = lib.mkOption {
+        description = "My type-safe function invocation.";
+        type = lib.types.submodule PATH/TO/function.nix;
+        readOnly = true;
+        default = {
+          input-type = lib.types.int;
+          output-type = lib.types.int;
+          implementation = x: x + x;
+        };
+      };
+    };
+    config = {
+      my-function.apply "1"
+    };
+  }
+  ```
+
+  A sample stack trace using this ends up like:
+
+  - `INVOKER.apply.<function body>``
+  - `function.nix`
+  - `INVOKER.wrapper.<function body>.output`
+  - `INVOKER.implementation.<function body>`
 */
 { config, lib, ... }:
 let