Flesh out documentation

pydtn/__init__.py

-"""pydtn is a module for simulating delay tolerant networks."""
+"""
+pydtn is a module for simulating delay tolerant networks.
+
+A simulation is made up from a Network which contains:
+- A group of nodes which are responsible for forwarding packets to each other.
+- A trace which defines when nodes come into contact and when they are no
+  longer in contact.
+- A traffic pattern which defines when a packet is created, which node is the
+  source, and which node is the destination.
+"""
 
 __all__ = [
     'Network',
@@ -31,7 +40,17 @@ class Network:
     """
     Network simulation.
 
-    TODO: elaborate.
+    Keyword Arguments:
+    - nodes -- the nodes of the network in a dictionary of id to node.
+    - trace -- a generator that yield Contact objects.
+    - traffic -- a generator that yields Traffic objects.
+
+    Running a simulation:
+    To run the simulation call the `run` method.
+
+    Statistics:
+    There are two ways to get statistics from the simulation, via either the
+    `stats` or the `stats_summary` property.
     """
 
     def __init__(self, nodes=None, trace=None, traffic=None):
@@ -159,7 +178,7 @@ class Packet:
     """An item to route through the network."""
 
     def __init__(self, network, traffic):
-
+        """Create a packet within a network, based on traffic."""
         self.network = network
         self._traffic = traffic
 
@@ -225,15 +244,17 @@ class Packet:
 
 
 class Buffer:
-    """A place for a node to hold packets."""
+    """
+    A place for a node to hold packets.
+
+    Stores the order that packet were added to the buffer.
+    Can be removed from while being iterated over.
+    """
 
     def __init__(self, capacity=None, **options):
         """
         Create a buffer.
 
-        Stores the order that packet were added to the buffer.
-        Can be removed from while being iterated over.
-
         Keyword arguments:
         capacity -- the maximum number of packets to hold (default infinity).
         """
@@ -274,7 +295,11 @@ class Buffer:
 
 
 class Node:
-    """Basic implementation of a node implements direct routing."""
+    """
+    Basic implementation of a node.
+
+    Forwards directly to destination node.
+    """
 
     class SendFailed(Exception):
         """Raised when a send fails."""
@@ -433,6 +458,9 @@ class EpidemicNode(Node):
         """
         Forward based on the epidemic heuristic.
 
+        Arguments:
+        packet -- packet to be forwarded.
+
         Epidemic Heuristic:
         - Forward the packet to all neighbours that I have not forwarded
           to so far.
@@ -449,6 +477,10 @@ class EpidemicNode(Node):
         """
         Call when a send succeeds.
 
+        Arguments:
+        packet -- packet that was sent successfully.
+        target -- the node that packet was sent to.
+
         Adds target to packet tracking.
         """
         super().send_success(packet, target)
@@ -477,6 +509,14 @@ class FloodingNode(Node):
 
         return forward
 
+    def send_success(self, packet, target):
+        """
+        Call when send suecceeds.
+
+        Do nothing, overrides default of removing from buffer.
+        """
+        pass
+
 
 Contact = namedtuple('Contact', ['time', 'a', 'b', 'join'])