more public api docs

Author: jacklowrie

src/chordnet/chordnet.py

@@ -4,7 +4,6 @@
 
 class ChordNet:
     """Interface for interacting with Chord networks."""
-
     _node: _Node
 
     def __init__(self,
@@ -15,7 +14,8 @@ def __init__(self,
         """Initializes a new Chord node.
 
         Args:
-            ip: IP address for the node.
+            ip: IP address for the node. This should be the public IP
+                (unless the whole ring is local, it is unlikely to be 127.0.0.1)
             port: Port number to listen on.
             interval: daemon interval (how often to 'sync' with the network)
         """
@@ -25,14 +25,17 @@ def __init__(self,
     def create(self) -> None:
         """Create a new ChordNet network (a new "ring").
 
-        This creates a new network with one node (this one).
+        This creates a new network with one node (this one), using the
+        ip and port passed to the class constructor.
         """
         self._node.create()
 
     def join(self, known_ip: str, known_port: int) -> None:
         """Joins an existing ChordNet network (an existing ring).
 
-        An existing chordnet can be joined through any node already on the ring.
+        An existing chordnet can be joined through any node already on running
+        on the ring. Note that this means a node cannot join itself to create
+        a ring, and trivially, joining itself once running is meaningless.
 
         Args:
             known_ip: IP address of an existing node in the Chord ring.
@@ -43,7 +46,9 @@ def join(self, known_ip: str, known_port: int) -> None:
     def leave(self) -> None:
         """Leave the current network.
 
-        Allows for a graceful shutdown of this node. Should be called before
-        program exit, but the network can recover if this does not happen.
+        Allows for a graceful shutdown of this node. This is optional and
+        can help the ring recover faster. It should be called before
+        program exit (or before a node shuts down in the network), but the
+        network can still recover if this does not happen.
         """
         pass