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