Clarify relationship between Region and PlacementZone

cloudbridge/providers/interfaces.py

@@ -740,61 +740,81 @@ class Snapshot(object):
         raise NotImplementedError('delete not implemented by this provider')
 
 
-class Region(object):
+class KeyPair(object):
 
     def name(self):
         """
-        Name of the region/zone.
+        Return the name of this key pair.
 
         :rtype: str
-        :return: Name of the region/zone.
+        :return: A name of this ssh key pair
         """
         raise NotImplementedError(
             'name not implemented by this provider')
 
-    def list_zones(self):
+    def material(self):
         """
-        List all available regions.
+        Unencrypted private key.
 
-        :rtype: list
-        :return: List of all the available regions.
+        :rtype: str
+        :return: Unencrypted private key.
         """
         raise NotImplementedError(
-            'list_zones not implemented by this provider')
+            'material not implemented by this provider')
 
 
-class KeyPair(object):
+class Region(object):
+    """
+    Represents a cloud region, typically a separate geographic area and will
+    contain at least one placement zone.
+    """
 
     def name(self):
         """
-        Return the name of this key pair.
+        Name of the region.
 
         :rtype: str
-        :return: A name of this ssh key pair
+        :return: Name of the region.
         """
         raise NotImplementedError(
             'name not implemented by this provider')
 
-    def material(self):
+    def list_zones(self):
         """
-        Unencrypted private key.
+        List all available placement zones within this region.
 
-        :rtype: str
-        :return: Unencrypted private key.
+        :rtype: list
+        :return: List of all the available placement zones.
         """
         raise NotImplementedError(
-            'material not implemented by this provider')
+            'list_zones not implemented by this provider')
 
 
 class PlacementZone(object):
     """
-    A placement zone object.
+    Represents a placement zone. A placement zone is contained within a Region.
     """
 
     def name(self):
+        """
+        Name of the placement zone.
+
+        :rtype: str
+        :return: Name of the placement zone.
+        """
         raise NotImplementedError(
             'PlacementZone.name not implemented by this provider')
 
+    def region_name(self):
+        """
+        A region this placement zone is associated with.
+
+        :rtype: str
+        :return: The name of the region the zone is associated with.
+        """
+        raise NotImplementedError(
+            'region_name not implemented by this provider')
+
 
 class InstanceTypesService(object):