From c5b5857a39a4a55059b585fae21968b533913b8c Mon Sep 17 00:00:00 2001
From: Ingolf Wagner <contact@ingolf-wagner.de>
Date: Fri, 7 Jun 2024 13:51:35 +0200
Subject: [PATCH] add clanlib.nix documentation

---
 nixos/lib/clanlib.nix | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/nixos/lib/clanlib.nix b/nixos/lib/clanlib.nix
index 855c628..6f19a6c 100644
--- a/nixos/lib/clanlib.nix
+++ b/nixos/lib/clanlib.nix
@@ -15,7 +15,13 @@ let
     else
       null;
 
-  # machine -> factvalue
+  # Example:
+  #
+  # readFactFromAllMachines zerotier-ip
+  # => {
+  #   machineA = "1.2.3.4";
+  #   machineB = "5.6.7.8";
+  # };
   readFactFromAllMachines = fact:
     let
       machines = allMachineNames;
@@ -24,8 +30,23 @@ let
     in
     filteredFacts;
 
-  # returns an Attrs of machines and it's facts which have all given facts set.
-  # machine -> fact -> value
+  # all given facts are are set and factvalues are never null.
+  #
+  # Example:
+  #
+  # readFactsFromAllMachines [ "zerotier-ip" "syncthing.pub" ]
+  # => {
+  #   machineA =
+  #     {
+  #       "zerotier-ip" = "1.2.3.4";
+  #       "synching.pub" = "1234";
+  #     };
+  #   machineB =
+  #     {
+  #       "zerotier-ip" = "5.6.7.8";
+  #       "synching.pub" = "23456719";
+  #     };
+  # };
   readFactsFromAllMachines = facts:
     let
       # machine -> fact -> factvalue