Update api_objects.py

Fix comments seen as problematic in code review.

vtds_provider_gcp/api_objects.py

@@ -94,15 +94,14 @@ def blade_ssh_key_paths(self, blade_type):
     def connect_blade(self, blade_type, instance, remote_port):
         """Establish an external connection to the specified remote
         port on the specified instance of the named Virtual Blade
-        type. Return a context manager (suitable for use in a 'with'
-        clause) yielding an APIBladeConnection object for the
-        connection. Upon leaving the 'with' context, the connection in
-        the APIBladeConnection is closed.
+        type. Return a BladeConnection object for the connection.
+        
+        BladeConnections are context managed, so if this is used
+        in a 'with' clause, upon leaving the 'with' context, the
+        connection in the BladeConnection is automatically closed.
 
-        This can also be used to connect to a host with an IP address
-        reachable by the blade if 'host' is specified. In this case,
-        the port will be tunneled through the blade to the specified
-        host instead of the blade itself.
+        To close the connection outside of a 'with' clause call
+        the __exit__() method on the BladeConnection.
 
         """
 
@@ -112,21 +111,30 @@ def connect_blades(self, remote_port, blade_types=None):
         on all the Virtual Blade instances on all the Virtual Blade
         types listed by name in 'blade_types'. If 'blade_types' is not
         provided or None, all available blade types are used. Return a
-        context manager (suitable for use in a 'with' clause) yielding
-        the list of APIBladeConnection objects representing the
-        connections. Upon leaving the 'with' context, all the
-        connections in the resulting list are closed.
+        BladeConnectionSet object representing the connections.
+        
+        BladeConnectionSets are context managed, so if this is used
+        in a 'with' clause, upon leaving the 'with' context, the
+        connections in the BladeConnectionSet are automatically closed.
+
+        To close the connections outside of a 'with' clause call
+        the __exit__() method on the BladeConnectionSet.
 
         """
 
     @abstractmethod
     def ssh_connect_blade(self, blade_type, instance, remote_port):
         """Establish an external connection to the SSH server
         port on the specified instance of the named Virtual Blade
-        type. Return a context manager (suitable for use in a 'with'
-        clause) yielding a BladeSSHConnection object for the
-        connection. Upon leaving the 'with' context, the connection in
-        the BladeSSHConnection is closed.
+        type. Return a BladeSSHConnection object for the
+        connection.
+        
+        BladeSSHConnection are context managed, so if this is used
+        in a 'with' clause, upon leaving the 'with' context, the
+        connection in the BladeSSHConnection is automatically closed.
+
+        To close the connection outside of a 'with' clause call
+        the __exit__() method on the BladeSSHConnection.
 
         """
 
@@ -136,10 +144,15 @@ def ssh_connect_blades(self, blade_types=None, remote_port=22):
         on all the Virtual Blade instances on all the Virtual Blade
         types listed by name in 'blade_types'. If 'blade_types' is not
         provided or None, all available blade types are used. Return a
-        context manager (suitable for use in a 'with' clause) yielding
-        the list of APIBladeConnection objects representing the
-        connections. Upon leaving the 'with' context, all the
-        connections in the resulting list are closed.
+        BladeSSHConnectionSet object representing the
+        connections.
+        
+        BladeSSHConnectionSets are context managed, so if this is used
+        in a 'with' clause, upon leaving the 'with' context, the
+        connections in the BladeSSHConnectionSet are automatically closed.
+
+        To close the connections outside of a 'with' clause call
+        the __exit__() method on the BladeSSHConnectionSet.
 
         """
 
@@ -217,7 +230,7 @@ def __exit__(
             exception_value=None,
             traceback=None
     ):
-        """Context departure handler to make BladeConnection
+        """Context exit handler to make BladeConnection
         objects usable with the 'with ... as' construct. This cleans
         up all resources associated with the BladeConnection on
         exit from the 'with' block context. Not called if the object
@@ -265,7 +278,7 @@ def __exit__(
             exception_value=None,
             traceback=None
     ):
-        """Context departure handler to make BladeConnectionSet
+        """Context exit handler to make BladeConnectionSet
         objects usable with the 'with ... as' construct. This cleans
         up all resources associated with the BladeConnectionSet on
         exit from the 'with' block context. Not called if the object
@@ -396,7 +409,7 @@ def __exit__(
             exception_value=None,
             traceback=None
     ):
-        """Context departure handler to make BladeSSHConnection objects
+        """Context exit handler to make BladeSSHConnection objects
         usable with the 'with ... as' construct. This cleans up all
         resources associated with the BladeSSHConnection on exit from
         the 'with' block context. Not called if the object is used