Router

- Documented `handle_ARP(Link link, string srcAddr, Message recvMesg)`

source/twine/core/arp.d

@@ -303,6 +303,7 @@ public class ArpManager : Receiver
                 Arp arpMesg;
                 if(recvMesg.decodeAs(arpMesg))
                 {
+                    logger.dbg("arpMesg, received: ", arpMesg, "from: ", srcAddr);
                     ArpReply reply;
                     if(arpMesg.getReply(reply))
                     {

source/twine/core/router.d

@@ -13,23 +13,49 @@ import core.sync.condition : Condition;
 import niknaks.functional : Optional;
 import twine.core.arp;
 
-// for data destined to yourself (todo, in future maybe have dest?)
+/** 
+ * This represents data passed
+ * from the router to a user
+ * data handler when data destined
+ * to your node arrives
+ */
 public struct UserDataPkt
 {
     private string src;
     private byte[] data;
 
+    /** 
+     * Constructs a new `UserDataPkt`
+     * with the provided network-layer
+     * source address and payload
+     *
+     * Params:
+     *   src = network-layer address
+     *   data = packet payload
+     */
     this(string src, byte[] data)
     {
         this.src = src;
         this.data = data;
     }
 
+    /** 
+     * Retrieve's the network-layer
+     * address of this packet
+     *
+     * Returns: the address
+     */
     public string getSrc()
     {
         return this.src;
     }
 
+    /** 
+     * Retrieve's the packet's
+     * payload
+     *
+     * Returns: the payload
+     */
     public byte[] getPayload()
     {
         return this.data;
@@ -101,12 +127,18 @@ public class Router : Receiver
         this(keyPairs, toDelegate(messageHandler), advFreq);
     }
 
+    /** 
+     * Starts the router
+     */
     public void start()
     {
         this.running = true;
         this.advThread.start();
     }
 
+    /** 
+     * Stops the router
+     */
     public void stop()
     {
         this.running = false;
@@ -116,16 +148,39 @@ public class Router : Receiver
         destroy(this.arp);
     }
 
+    /** 
+     * Returns the link manager
+     * instance of this router
+     *
+     * Returns: the `LinkManager`
+     */
     public final LinkManager getLinkMan()
     {
         return cast(LinkManager)this.linkMan;
     }
 
+    /** 
+     * Returns the public key associated
+     * with this router
+     *
+     * Returns: the public key
+     */
     private string getPublicKey()
     {
         return this.keyPairs[0];
     }
 
+    /** 
+     * Process a given payload from a given
+     * link and source link-layer address
+     *
+     * Params:
+     *   link = the `Link` from which the
+     * packet was received
+     *   data = the data itself
+     *   srcAddr = the link-layer address
+     * which is the source of this packet
+     */
     private void process(Link link, byte[] data, string srcAddr)
     {
         logger.dbg("Received data from link '", link, "' with ", data.length, " many bytes (llSrc: "~srcAddr~")");
@@ -163,6 +218,14 @@ public class Router : Receiver
 
     private bool isForwarding = true; // todo, make togglable during runtime
 
+    /** 
+     * Given a packet this will
+     * attempt to forward it
+     *
+     * Params:
+     *   dataPkt = the packet as
+     * a `User`
+     */
     private void attemptForward(Data dataPkt)
     {
         // lookup route to host
@@ -207,6 +270,21 @@ public class Router : Receiver
         }
     }
 
+    /** 
+     * Handles a packet that contains user data.
+     *
+     * Depending on who it was destined to this
+     * will either call a user data packet handler
+     * or it will attempt to forward it (if forwarding
+     * is enabled)
+     *
+     * Params:
+     *   link = the `Link` from which the packet
+     * was received
+     *   srcAddr = the link-layer source address of
+     * the packet
+     *   recvMesg = the received `Message`
+     */
     private void handle_DATA(Link link, string srcAddr, Message recvMesg)
     {
         Data dataPkt;
@@ -241,6 +319,23 @@ public class Router : Receiver
         }
     }
 
+    /** 
+     * Handles a packet which contains
+     * ARP data in it. It detects
+     * firstly if it is an ARP request
+     * (as responses are ignored) and
+     * then, if so, it checks that the
+     * requested network-layer address
+     * matches our public key - and
+     * then proceeds to answer it.
+     *
+     * Params:
+     *   link = the `Link` from which
+     * this packet was received
+     *   srcAddr = the link-layer
+     * source address
+     *   recvMesg = the received message
+     */
     private void handle_ARP(Link link, string srcAddr, Message recvMesg)
     {
         Arp arpMesg;