diff --git a/emuvim/api/zerorpcapi.py b/emuvim/api/zerorpcapi.py
index 7be3f60..71505a5 100644
--- a/emuvim/api/zerorpcapi.py
+++ b/emuvim/api/zerorpcapi.py
@@ -11,6 +11,14 @@
 
 
 class ZeroRpcApiEndpoint(object):
+    """
+    Simple API endpoint that offers a zerorpc-based
+    interface. This interface will be used by the
+    default command line client.
+    It can be used as a reference to implement
+    REST interfaces providing the same semantics,
+    like e.g. OpenStack compute API.
+    """
 
     def __init__(self, listenip, port):
         self.dcs = {}
@@ -38,12 +46,18 @@
 
 
 class MultiDatacenterApi(object):
+    """
+        Just pass through the corresponding request to the
+        selected data center. Do not implement provisioning
+        logic here because will will have multiple API
+        endpoint implementations at the end.
+    """
 
     def __init__(self, dcs):
         self.dcs = dcs
 
     def compute_action_start(self, dc_name, compute_name):
-        # TODO return UUID / IP ?
+        # TODO what to return UUID / IP ?
         logging.debug("RPC CALL: compute start")
         if dc_name in self.dcs:
             self.dcs[dc_name].addCompute(compute_name)
diff --git a/emuvim/cli/__main__.py b/emuvim/cli/__main__.py
index 95ce01e..4c55916 100644
--- a/emuvim/cli/__main__.py
+++ b/emuvim/cli/__main__.py
@@ -1,6 +1,11 @@
 """
  For now only a dummy client. Connects to the zerorpc interface of the
  emulator and performs some actions (start/stop/list).
+
+ We will provide a full CLI here later on which looks like:
+
+ cli compute start dc1 my_name flavor_a
+ cli network create dc1 11.0.0.0/24
 """
 import time
 import zerorpc
diff --git a/emuvim/dcemulator/net.py b/emuvim/dcemulator/net.py
index 586b1e8..e0f41e2 100644
--- a/emuvim/dcemulator/net.py
+++ b/emuvim/dcemulator/net.py
@@ -14,6 +14,12 @@
 
 
 class DCNetwork(object):
+    """
+    Wraps the original Mininet class and provides
+    methods to add data centers, switches, etc.
+
+    This class is used by topology definition scripts.
+    """
 
     def __init__(self):
         self.dcs = {}
@@ -85,4 +91,3 @@
 
     def CLI(self):
         CLI(self.mnet)
-
diff --git a/emuvim/dcemulator/node.py b/emuvim/dcemulator/node.py
index 3111735..5e5def0 100644
--- a/emuvim/dcemulator/node.py
+++ b/emuvim/dcemulator/node.py
@@ -12,6 +12,8 @@
     """
     Represents a logical data center to which compute resources
     (Docker containers) can be added at runtime.
+
+    Will also implement resource bookkeeping in later versions.
     """
 
     def __init__(self, name):
@@ -40,6 +42,10 @@
         pass
 
     def addCompute(self, name):
+        """
+        Create a new container as compute resource and connect it to this
+        data center.
+        """
         #TODO remove mnet shortcut to have a clean API
         #TODO connect container to DC's swtich
         self.net.mnet.addDocker("%s.%s" % (self.name, name), dimage="ubuntu")
diff --git a/emuvim/example_topology.py b/emuvim/example_topology.py
index a21cdba..fce0698 100644
--- a/emuvim/example_topology.py
+++ b/emuvim/example_topology.py
@@ -2,6 +2,17 @@
 This is an example topology for the distributed cloud emulator (dcemulator).
 (c) 2015 by Manuel Peuster <manuel.peuster@upb.de>
 
+
+This is an example that shows how a user of the emulation tool can
+define network topologies with multiple emulated cloud data centers.
+
+The definition is done with a Python API which looks very similar to the
+Mininet API (in fact it is a wrapper for it).
+
+We only specify the topology *between* data centers not within a single
+data center (data center internal setups or placements are not of interest,
+we want to experiment with VNF chains deployed across multiple PoPs).
+
 The original Mininet API has to be completely hidden and not be used by this
 script.
 """
@@ -13,40 +24,80 @@
 
 
 def create_topology1():
-    # TODO add long comments to this example to show people how to use this
-    # initialize network
+    """
+    1. Create a data center network object (DCNetwork)
+    """
     net = DCNetwork()
 
-    # add data centers
+    """
+    2. Add (logical) data centers to the topology
+       (each data center is one "bigswitch" in our simplified
+        first prototype)
+    """
     dc1 = net.addDatacenter("dc1")
     dc2 = net.addDatacenter("dc2")
     dc3 = net.addDatacenter("dc3")
     dc4 = net.addDatacenter("dc4")
-    # add additional SDN switches to our topology
+
+    """
+    3. You can add additional SDN switches for data center
+       interconnections to the network.
+    """
     s1 = net.addSwitch("s1")
-    # add links between data centers
+
+    """
+    4. Add links between your data centers and additional switches
+       to define you topology.
+       These links can use Mininet's features to limit bw, add delay or jitter.
+    """
     net.addLink(dc1, dc2)
     net.addLink("dc1", s1)
     net.addLink(s1, "dc3")
     net.addLink(s1, dc4)
 
-    # create and start APIs (to access emulated cloud data centers)
+    """
+    5. We want to access and control our data centers from the outside,
+       e.g., we want to connect an orchestrate to start/stop compute
+       resources aka. VNFs (represented by Docker containers in the emulated)
+
+       So we need to instantiate API endpoints (e.g. a zerorpc or REST
+       interface). Depending on the endpoint implementations, we can connect
+       one or more data centers to it, which can then be controlled through
+       this API, e.g., start/stop/list compute instances.
+    """
+    # create a new instance of a endpoint implementation
     zapi1 = ZeroRpcApiEndpoint("0.0.0.0", 4242)
+    # connect data centers to this endpoint
     zapi1.connectDatacenter(dc1)
     zapi1.connectDatacenter(dc2)
+    # run API endpoint server (in another thread, don't block)
     zapi1.start()
-    # lets also create a second API endpoint on another port to
-    # demonstrate hat you can have one endpoint for each of
-    # your data centers
+
+    """
+    5.1. For our example, we create a second endpoint to illustrate that
+         this is support by our design. This feature allows us to have
+         one API endpoint for each data center. This makes the emulation
+         environment more realistic because you can easily create one
+         OpenStack-like REST API endpoint for *each* data center.
+         This will look like a real-world multi PoP/data center deployment
+         from the perspective of an orchestrator.
+    """
     zapi2 = ZeroRpcApiEndpoint("0.0.0.0", 4343)
     zapi2.connectDatacenter(dc3)
     zapi2.connectDatacenter(dc4)
     zapi2.start()
 
-    # start network
+    """
+    6. Finally we are done and can start our network (the emulator).
+       We can also enter the Mininet CLI to interactively interact
+       with our compute resources (just like in default Mininet).
+       But we can also implement fully automated experiments that
+       can be executed again and again.
+    """
     net.start()
-    net.CLI()  # TODO remove this when we integrate APIs?
-    net.stop()  # TODO remove this when we integrate APIs?
+    net.CLI()
+    # when the user types exit in the CLI, we stop the emulator
+    net.stop()
 
 
 def main():