doc: add a pile of documentation to teh dns file

applications/dns/dns.nix

@@ -19,7 +19,7 @@
 
   # get the ip's of our servers
   servers = lib.lists.naturalSort (lib.lists.unique (
-    lib.lists.forEach (sort_records_server records) (x: x.value)
+    lib.lists.forEach (sort_records_a_server records) (x: x.value)
   ));
 
   domains_owned = [
@@ -33,9 +33,12 @@
 
   # gets a list of records that match this type
   filter_records_type = records: r_type: builtins.filter (x: x.r_type == r_type) records;
-  filter_records_server = records: builtins.filter (x: builtins.hasAttr "server" x && x.server) (filter_records_type records "A");
+  # Get all the A records that are for servers (base record for them)
+  filter_records_a_server = records: builtins.filter (x: builtins.hasAttr "server" x && x.server) (filter_records_type records "A");
+  # Every other A record
   filter_records_a = records: builtins.filter (x: builtins.hasAttr "server" x && !x.server) (filter_records_type records "A");
 
+  # These functions are to get the final 3 digits of an IP address so we can use them for reverse pointer
   process_ptr = records: lib.lists.forEach records (x: process_ptr_sub x);
   process_ptr_sub = record: {
     record = builtins.substring 9 3 record.record;
@@ -44,39 +47,49 @@
   };
   ip_ptr_to_int = ip: lib.strings.toInt (builtins.substring 9 3 ip);
 
-  sort_records_server = records: builtins.sort (a: b: a.record < b.record) (filter_records_server records);
+  # filter and sort records so we cna group them in the right place later
+  sort_records_a_server = records: builtins.sort (a: b: a.record < b.record) (filter_records_a_server records);
   sort_records_a = records: builtins.sort (a: b: (ip_ptr_to_int a.value) < (ip_ptr_to_int b.value)) (filter_records_a records);
   sort_records_cname = records: builtins.sort (a: b: a.value < b.value) (filter_records_type records "CNAME");
   sort_records_ptr = records: builtins.sort (a: b: (lib.strings.toInt a.record) < (lib.strings.toInt b.record)) (process_ptr (filter_records_type records "PTR"));
   sort_records_srv = records: builtins.sort (a: b: a.record < b.record) (filter_records_type records "SRV");
 
+  # a tad overkill but type guarding is useful
   max = x: y:
     assert builtins.isInt x;
     assert builtins.isInt y;
       if x < y
       then y
       else x;
+  
+  # get teh max length of a list of strings
   max_len = records: lib.lists.foldr (a: b: (max a b)) 0 (lib.lists.forEach records (record: lib.strings.stringLength record.record));
 
+  # now that we can get teh max lenth of a list of strings 
+  # we can pad it out to the max len +1
+  # this is so that teh generated file is easier for a human to read
   format_records = records: let
     offset = (max_len records) + 1;
   in
     lib.strings.concatMapStrings (x: "${padString x.record offset} IN ${padString x.r_type 5} ${x.value}\n") records;
 
-  # small function to trim it down a tad
+  # small function to add spaces until it reaches teh required length
   padString = text: length: fixedWidthString_post length " " text;
 
   # like lib.strings.fixedWidthString but postfix
+  # recursive function to extend a string up to a limit
   fixedWidthString_post = width: filler: str: let
     strw = lib.stringLength str;
     reqWidth = width - (lib.stringLength filler);
   in
+    # this is here because we were manually setting teh length, now max_len does that for us
     assert lib.assertMsg (strw <= width) "fixedWidthString_post: requested string length (${toString width}) must not be shorter than actual length (${toString strw})";
       if strw == width
       then str
       else (fixedWidthString_post reqWidth filler str) + filler;
 
   # base config for domains we own (skynet.ie, csn.ul.ie, ulcompsoc.ie)
+  # ";" are comments in this file
   get_config_file = (
     domain: records: ''
       $TTL 60  ; 1 minute
@@ -97,7 +110,7 @@
       ; ------------------------------------------
       ; Server Names (A Records)
       ; ------------------------------------------
-      ${format_records (sort_records_server records)}
+      ${format_records (sort_records_a_server records)}
 
       ; ------------------------------------------
       ; A (non server names
@@ -123,8 +136,6 @@
       ; SRV
       ; ------------------------------------------
       ${format_records (sort_records_srv records)}
-
-
     ''
   );
 
@@ -154,26 +165,26 @@
     ''
   );
 
-  # arrys  of teh two nameservers
+  # arrays  of teh two nameservers
-  tmp1 = ["193.1.99.109"];
+  nameserver_1 = ["193.1.99.109"];
-  tmp2 = ["193.1.99.120"];
+  nameserver_2 = ["193.1.99.120"];
 
   primaries = (
     if cfg.server.primary
     then
       # primary servers have no primaries (ones they listen to)
       []
-    else if builtins.elem cfg.server.ip tmp1
+    else if builtins.elem cfg.server.ip nameserver_1
-    then tmp2
+    then nameserver_2
-    else tmp1
+    else nameserver_1
   );
 
   secondaries = (
     if cfg.server.primary
     then
-      if builtins.elem cfg.server.ip tmp1
+      if builtins.elem cfg.server.ip nameserver_1
-      then tmp2
+      then nameserver_2
-      else tmp1
+      else nameserver_1
     else []
   );
 
@@ -192,17 +203,19 @@
       # The UNIX file mode bits
       mode = "0664";
 
+      # content of the file
       text = text;
     };
   };
-  # (text.owned "csn.ul.ie")
 
   # standard function to create the etc file, pass in the text and domain and it makes it
   create_entry_etc = domain: type: let
     domain_records = lib.lists.filter (x: x.domain == domain) records;
   in
+    # this is the main type of record that most folks are used to
     if type == "owned"
     then create_entry_etc_sub domain (get_config_file domain domain_records)
+    # reverse lookups allow for using an IP to find domains pointing to it
     else if type == "reverse"
     then create_entry_etc_sub domain (get_config_file_rev domain)
     else {};
@@ -334,6 +347,7 @@ in {
       group = "named";
     };
 
+    # basic but ensure teh dns ports are open
     networking.firewall = {
       allowedTCPPorts = [53];
       allowedUDPPorts = [53];