Move documentation from nova.virt.fake into nova.virt.driver.

2 files changed, 270 insertions, 297 deletions

diff --git a/nova/virt/driver.py b/nova/virt/driver.py
index 20af2666d..93290aba7 100644
--- a/nova/virt/driver.py
+++ b/nova/virt/driver.py
@@ -62,11 +62,41 @@ def block_device_info_get_mapping(block_device_info):
 class ComputeDriver(object):
     """Base class for compute drivers.
 
-    Lots of documentation is currently on fake.py.
+    The interface to this class talks in terms of 'instances' (Amazon EC2 and
+    internal Nova terminology), by which we mean 'running virtual machine'
+    (XenAPI terminology) or domain (Xen or libvirt terminology).
+
+    An instance has an ID, which is the identifier chosen by Nova to represent
+    the instance further up the stack.  This is unfortunately also called a
+    'name' elsewhere.  As far as this layer is concerned, 'instance ID' and
+    'instance name' are synonyms.
+
+    Note that the instance ID or name is not human-readable or
+    customer-controlled -- it's an internal ID chosen by Nova.  At the
+    nova.virt layer, instances do not have human-readable names at all -- such
+    things are only known higher up the stack.
+
+    Most virtualization platforms will also have their own identity schemes,
+    to uniquely identify a VM or domain.  These IDs must stay internal to the
+    platform-specific layer, and never escape the connection interface.  The
+    platform-specific layer is responsible for keeping track of which instance
+    ID maps to which platform-specific ID, and vice versa.
+
+    In contrast, the list_disks and list_interfaces calls may return
+    platform-specific IDs.  These identify a specific virtual disk or specific
+    virtual network interface, and these IDs are opaque to the rest of Nova.
+
+    Some methods here take an instance of nova.compute.service.Instance.  This
+    is the datastructure used by nova.compute to store details regarding an
+    instance, and pass them into this layer.  This layer is responsible for
+    translating that generic datastructure into terms that are specific to the
+    virtualization platform.
+
     """
 
     def init_host(self, host):
-        """Adopt existing VM's running here"""
+        """Initialize anything that is necessary for the driver to function,
+        including catching up with currently running VM's on the given host."""
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
@@ -74,6 +104,7 @@ class ComputeDriver(object):
         """Get the current status of an instance, by name (not ID!)
 
         Returns a dict containing:
+
         :state:           the running state, one of the power_state codes
         :max_mem:         (int) the maximum memory in KBytes allowed
         :mem:             (int) the memory in KBytes used by the domain
@@ -84,6 +115,10 @@ class ComputeDriver(object):
         raise NotImplementedError()
 
     def list_instances(self):
+        """
+        Return the names of all the instances known to the virtualization
+        layer, as a list.
+        """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
@@ -94,28 +129,53 @@ class ComputeDriver(object):
 
     def spawn(self, context, instance,
               network_info=None, block_device_info=None):
-        """Launch a VM for the specified instance"""
+        """
+        Create a new instance/VM/domain on the virtualization platform.
+
+        Once this successfully completes, the instance should be
+        running (power_state.RUNNING).
+
+        If this fails, any partial instance should be completely
+        cleaned up, and the virtualization platform should be in the state
+        that it was before this call began.
+
+        :param context: security context
+        :param instance: Instance of {nova.compute.service.Instance}.
+                         This function should use the data there to guide
+                         the creation of the new instance.
+        :param network_info:
+           :py:meth:`~nova.network.manager.NetworkManager.get_instance_nw_info`
+        :param block_device_info:
+        """
         raise NotImplementedError()
 
     def destroy(self, instance, network_info, cleanup=True):
         """Destroy (shutdown and delete) the specified instance.
 
         The given parameter is an instance of nova.compute.service.Instance,
-        and so the instance is being specified as instance.name.
-
-        The work will be done asynchronously.  This function returns a
-        task that allows the caller to detect when it is complete.
 
         If the instance is not found (for example if networking failed), this
         function should still succeed.  It's probably a good idea to log a
         warning in that case.
 
+        :param instance: Instance of {nova.compute.service.Instance} and so
+                         the instance is being specified as instance.name.
+        :param network_info:
+           :py:meth:`~nova.network.manager.NetworkManager.get_instance_nw_info`
+        :param cleanup:
+
         """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
     def reboot(self, instance, network_info):
-        """Reboot specified VM"""
+        """Reboot the specified instance.
+
+        :param instance: Instance of {nova.compute.service.Instance} and so
+                         the instance is being specified as instance.name.
+        :param network_info:
+           :py:meth:`~nova.network.manager.NetworkManager.get_instance_nw_info`
+        """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
@@ -140,31 +200,60 @@ class ComputeDriver(object):
         raise NotImplementedError()
 
     def get_host_ip_addr(self):
+        """
+        Retrieves the IP address of the dom0
+        """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
     def attach_volume(self, context, instance_id, volume_id, mountpoint):
+        """Attach the disk at device_path to the instance at mountpoint"""
         raise NotImplementedError()
 
     def detach_volume(self, context, instance_id, volume_id):
+        """Detach the disk attached to the instance at mountpoint"""
         raise NotImplementedError()
 
-    def compare_cpu(self, context, cpu_info):
+    def compare_cpu(self, cpu_info):
+        """Compares given cpu info against host
+
+        Before attempting to migrate a VM to this host,
+        compare_cpu is called to ensure that the VM will
+        actually run here.
+
+        :param cpu_info: (str) JSON structure describing the source CPU.
+        :returns: None if migration is acceptable
+        :raises: :py:class:`~nova.exception.InvalidCPUInfo` if migration
+                 is not acceptable.
+        """
         raise NotImplementedError()
 
     def migrate_disk_and_power_off(self, instance, dest):
-        """Transfers the VHD of a running instance to another host, then shuts
-        off the instance copies over the COW disk"""
+        """
+        Transfers the disk of a running instance in multiple phases, turning
+        off the instance before the end.
+        """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
     def snapshot(self, context, instance, image_id):
-        """Create snapshot from a running VM instance."""
+        """
+        Snapshots the specified instance.
+
+        The given parameter is an instance of nova.compute.service.Instance,
+        and so the instance is being specified as instance.name.
+
+        The second parameter is the name of the snapshot.
+        """
         raise NotImplementedError()
 
     def finish_migration(self, context, instance, disk_info, network_info,
                          resize_instance):
-        """Completes a resize, turning on the migrated instance"""
+        """Completes a resize, turning on the migrated instance
+
+        :param network_info:
+           :py:meth:`~nova.network.manager.NetworkManager.get_instance_nw_info`
+        """
         raise NotImplementedError()
 
     def revert_migration(self, instance):
@@ -173,7 +262,7 @@ class ComputeDriver(object):
         raise NotImplementedError()
 
     def pause(self, instance, callback):
-        """Pause VM instance"""
+        """Pause the specified instance."""
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
@@ -218,15 +307,15 @@ class ComputeDriver(object):
                        post_method, recover_method):
         """Spawning live_migration operation for distributing high-load.
 
-        :params ctxt: security context
-        :params instance_ref:
+        :param ctxt: security context
+        :param instance_ref:
             nova.db.sqlalchemy.models.Instance object
             instance object that is migrated.
-        :params dest: destination host
-        :params post_method:
+        :param dest: destination host
+        :param post_method:
             post operation method.
             expected nova.compute.manager.post_live_migration.
-        :params recover_method:
+        :param recover_method:
             recovery method when any exception occurs.
             expected nova.compute.manager.recover_live_migration.
 
@@ -235,15 +324,69 @@ class ComputeDriver(object):
         raise NotImplementedError()
 
     def refresh_security_group_rules(self, security_group_id):
+        """This method is called after a change to security groups.
+
+        All security groups and their associated rules live in the datastore,
+        and calling this method should apply the updated rules to instances
+        running the specified security group.
+
+        An error should be raised if the operation cannot complete.
+
+        """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
     def refresh_security_group_members(self, security_group_id):
+        """This method is called when a security group is added to an instance.
+
+        This message is sent to the virtualization drivers on hosts that are
+        running an instance that belongs to a security group that has a rule
+        that references the security group identified by `security_group_id`.
+        It is the responsiblity of this method to make sure any rules
+        that authorize traffic flow with members of the security group are
+        updated and any new members can communicate, and any removed members
+        cannot.
+
+        Scenario:
+            * we are running on host 'H0' and we have an instance 'i-0'.
+            * instance 'i-0' is a member of security group 'speaks-b'
+            * group 'speaks-b' has an ingress rule that authorizes group 'b'
+            * another host 'H1' runs an instance 'i-1'
+            * instance 'i-1' is a member of security group 'b'
+
+            When 'i-1' launches or terminates we will recieve the message
+            to update members of group 'b', at which time we will make
+            any changes needed to the rules for instance 'i-0' to allow
+            or deny traffic coming from 'i-1', depending on if it is being
+            added or removed from the group.
+
+        In this scenario, 'i-1' could just as easily have been running on our
+        host 'H0' and this method would still have been called.  The point was
+        that this method isn't called on the host where instances of that
+        group are running (as is the case with
+        :method:`refresh_security_group_rules`) but is called where references
+        are made to authorizing those instances.
+
+        An error should be raised if the operation cannot complete.
+
+        """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
     def refresh_provider_fw_rules(self, security_group_id):
-        """See: nova/virt/fake.py for docs."""
+        """This triggers a firewall update based on database changes.
+
+        When this is called, rules have either been added or removed from the
+        datastore.  You can retrieve rules with
+        :method:`nova.db.api.provider_fw_rule_get_all`.
+
+        Provider rules take precedence over security group rules.  If an IP
+        would be allowed by a security group ingress rule, but blocked by
+        a provider rule, then packets from the IP are dropped.  This includes
+        intra-project traffic in the case of the allow_project_net_traffic
+        flag for the libvirt-derived classes.
+
+        """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
@@ -284,18 +427,38 @@ class ComputeDriver(object):
         raise NotImplementedError()
 
     def set_admin_password(self, context, instance_id, new_pass=None):
-        """Set the root/admin password for an instance on this server."""
+        """
+        Set the root password on the specified instance.
+
+        The first parameter is an instance of nova.compute.service.Instance,
+        and so the instance is being specified as instance.name. The second
+        parameter is the value of the new password.
+        """
         raise NotImplementedError()
 
     def inject_file(self, instance, b64_path, b64_contents):
-        """Create a file on the VM instance. The file path and contents
-        should be base64-encoded.
+        """
+        Writes a file on the specified instance.
+
+        The first parameter is an instance of nova.compute.service.Instance,
+        and so the instance is being specified as instance.name. The second
+        parameter is the base64-encoded path to which the file is to be
+        written on the instance; the third is the contents of the file, also
+        base64-encoded.
         """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
     def agent_update(self, instance, url, md5hash):
-        """Update agent on the VM instance."""
+        """
+        Update agent on the specified instance.
+
+        The first parameter is an instance of nova.compute.service.Instance,
+        and so the instance is being specified as instance.name. The second
+        parameter is the URL of the agent to be fetched and updated on the
+        instance; the third is the md5 hash of the file for verification
+        purposes.
+        """
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
 
@@ -322,3 +485,83 @@ class ComputeDriver(object):
         """Plugs in VIFs to networks."""
         # TODO(Vek): Need to pass context in for access to auth_token
         raise NotImplementedError()
+
+    def update_host_status(self):
+        """Refresh host stats"""
+        raise NotImplementedError()
+
+    def get_host_stats(self, refresh=False):
+        """Return currently known host stats"""
+        raise NotImplementedError()
+
+    def list_disks(self, instance_name):
+        """
+        Return the IDs of all the virtual disks attached to the specified
+        instance, as a list.  These IDs are opaque to the caller (they are
+        only useful for giving back to this layer as a parameter to
+        disk_stats).  These IDs only need to be unique for a given instance.
+
+        Note that this function takes an instance ID.
+        """
+        raise NotImplementedError()
+
+    def list_interfaces(self, instance_name):
+        """
+        Return the IDs of all the virtual network interfaces attached to the
+        specified instance, as a list.  These IDs are opaque to the caller
+        (they are only useful for giving back to this layer as a parameter to
+        interface_stats).  These IDs only need to be unique for a given
+        instance.
+
+        Note that this function takes an instance ID.
+        """
+        raise NotImplementedError()
+
+    def resize(self, instance, flavor):
+        """
+        Resizes/Migrates the specified instance.
+
+        The flavor parameter determines whether or not the instance RAM and
+        disk space are modified, and if so, to what size.
+        """
+        raise NotImplementedError()
+
+    def block_stats(self, instance_name, disk_id):
+        """
+        Return performance counters associated with the given disk_id on the
+        given instance_name.  These are returned as [rd_req, rd_bytes, wr_req,
+        wr_bytes, errs], where rd indicates read, wr indicates write, req is
+        the total number of I/O requests made, bytes is the total number of
+        bytes transferred, and errs is the number of requests held up due to a
+        full pipeline.
+
+        All counters are long integers.
+
+        This method is optional.  On some platforms (e.g. XenAPI) performance
+        statistics can be retrieved directly in aggregate form, without Nova
+        having to do the aggregation.  On those platforms, this method is
+        unused.
+
+        Note that this function takes an instance ID.
+        """
+        raise NotImplementedError()
+
+    def interface_stats(self, instance_name, iface_id):
+        """
+        Return performance counters associated with the given iface_id on the
+        given instance_id.  These are returned as [rx_bytes, rx_packets,
+        rx_errs, rx_drop, tx_bytes, tx_packets, tx_errs, tx_drop], where rx
+        indicates receive, tx indicates transmit, bytes and packets indicate
+        the total number of bytes or packets transferred, and errs and dropped
+        is the total number of packets failed / dropped.
+
+        All counters are long integers.
+
+        This method is optional.  On some platforms (e.g. XenAPI) performance
+        statistics can be retrieved directly in aggregate form, without Nova
+        having to do the aggregation.  On those platforms, this method is
+        unused.
+
+        Note that this function takes an instance ID.
+        """
+        raise NotImplementedError()
diff --git a/nova/virt/fake.py b/nova/virt/fake.py
index dc0628772..13b7aeab5 100644
--- a/nova/virt/fake.py
+++ b/nova/virt/fake.py
@@ -48,37 +48,7 @@ class FakeInstance(object):
 
 
 class FakeConnection(driver.ComputeDriver):
-    """
-    The interface to this class talks in terms of 'instances' (Amazon EC2 and
-    internal Nova terminology), by which we mean 'running virtual machine'
-    (XenAPI terminology) or domain (Xen or libvirt terminology).
-
-    An instance has an ID, which is the identifier chosen by Nova to represent
-    the instance further up the stack.  This is unfortunately also called a
-    'name' elsewhere.  As far as this layer is concerned, 'instance ID' and
-    'instance name' are synonyms.
-
-    Note that the instance ID or name is not human-readable or
-    customer-controlled -- it's an internal ID chosen by Nova.  At the
-    nova.virt layer, instances do not have human-readable names at all -- such
-    things are only known higher up the stack.
-
-    Most virtualization platforms will also have their own identity schemes,
-    to uniquely identify a VM or domain.  These IDs must stay internal to the
-    platform-specific layer, and never escape the connection interface.  The
-    platform-specific layer is responsible for keeping track of which instance
-    ID maps to which platform-specific ID, and vice versa.
-
-    In contrast, the list_disks and list_interfaces calls may return
-    platform-specific IDs.  These identify a specific virtual disk or specific
-    virtual network interface, and these IDs are opaque to the rest of Nova.
-
-    Some methods here take an instance of nova.compute.service.Instance.  This
-    is the datastructure used by nova.compute to store details regarding an
-    instance, and pass them into this layer.  This layer is responsible for
-    translating that generic datastructure into terms that are specific to the
-    virtualization platform.
-    """
+    """Fake hypervisor driver"""
 
     def __init__(self):
         self.instances = {}
@@ -105,17 +75,9 @@ class FakeConnection(driver.ComputeDriver):
         return cls._instance
 
     def init_host(self, host):
-        """
-        Initialize anything that is necessary for the driver to function,
-        including catching up with currently running VM's on the given host.
-        """
         return
 
     def list_instances(self):
-        """
-        Return the names of all the instances known to the virtualization
-        layer, as a list.
-        """
         return self.instances.keys()
 
     def _map_to_instance_info(self, instance):
@@ -131,167 +93,54 @@ class FakeConnection(driver.ComputeDriver):
 
     def spawn(self, context, instance,
               network_info=None, block_device_info=None):
-        """
-        Create a new instance/VM/domain on the virtualization platform.
-
-        The given parameter is an instance of nova.compute.service.Instance.
-        This function should use the data there to guide the creation of
-        the new instance.
-
-        The work will be done asynchronously.  This function returns a
-        task that allows the caller to detect when it is complete.
-
-        Once this successfully completes, the instance should be
-        running (power_state.RUNNING).
-
-        If this fails, any partial instance should be completely
-        cleaned up, and the virtualization platform should be in the state
-        that it was before this call began.
-        """
-
         name = instance.name
         state = power_state.RUNNING
         fake_instance = FakeInstance(name, state)
         self.instances[name] = fake_instance
 
     def snapshot(self, context, instance, name):
-        """
-        Snapshots the specified instance.
-
-        The given parameter is an instance of nova.compute.service.Instance,
-        and so the instance is being specified as instance.name.
-
-        The second parameter is the name of the snapshot.
-
-        The work will be done asynchronously.  This function returns a
-        task that allows the caller to detect when it is complete.
-        """
         pass
 
     def reboot(self, instance, network_info):
-        """
-        Reboot the specified instance.
-
-        The given parameter is an instance of nova.compute.service.Instance,
-        and so the instance is being specified as instance.name.
-
-        The work will be done asynchronously.  This function returns a
-        task that allows the caller to detect when it is complete.
-        """
         pass
 
     def get_host_ip_addr(self):
-        """
-        Retrieves the IP address of the dom0
-        """
-        pass
+        return '192.168.0.1'
 
     def resize(self, instance, flavor):
-        """
-        Resizes/Migrates the specified instance.
-
-        The flavor parameter determines whether or not the instance RAM and
-        disk space are modified, and if so, to what size.
-
-        The work will be done asynchronously. This function returns a task
-        that allows the caller to detect when it is complete.
-        """
         pass
 
     def set_admin_password(self, instance, new_pass):
-        """
-        Set the root password on the specified instance.
-
-        The first parameter is an instance of nova.compute.service.Instance,
-        and so the instance is being specified as instance.name. The second
-        parameter is the value of the new password.
-
-        The work will be done asynchronously.  This function returns a
-        task that allows the caller to detect when it is complete.
-        """
         pass
 
     def inject_file(self, instance, b64_path, b64_contents):
-        """
-        Writes a file on the specified instance.
-
-        The first parameter is an instance of nova.compute.service.Instance,
-        and so the instance is being specified as instance.name. The second
-        parameter is the base64-encoded path to which the file is to be
-        written on the instance; the third is the contents of the file, also
-        base64-encoded.
-
-        The work will be done asynchronously.  This function returns a
-        task that allows the caller to detect when it is complete.
-        """
         pass
 
     def agent_update(self, instance, url, md5hash):
-        """
-        Update agent on the specified instance.
-
-        The first parameter is an instance of nova.compute.service.Instance,
-        and so the instance is being specified as instance.name. The second
-        parameter is the URL of the agent to be fetched and updated on the
-        instance; the third is the md5 hash of the file for verification
-        purposes.
-
-        The work will be done asynchronously.  This function returns a
-        task that allows the caller to detect when it is complete.
-        """
         pass
 
     def rescue(self, context, instance, callback, network_info):
-        """
-        Rescue the specified instance.
-        """
         pass
 
     def unrescue(self, instance, callback, network_info):
-        """
-        Unrescue the specified instance.
-        """
         pass
 
     def poll_rescued_instances(self, timeout):
-        """Poll for rescued instances"""
         pass
 
     def migrate_disk_and_power_off(self, instance, dest):
-        """
-        Transfers the disk of a running instance in multiple phases, turning
-        off the instance before the end.
-        """
-        pass
-
-    def attach_disk(self, instance, disk_info):
-        """
-        Attaches the disk to an instance given the metadata disk_info
-        """
         pass
 
     def pause(self, instance, callback):
-        """
-        Pause the specified instance.
-        """
         pass
 
     def unpause(self, instance, callback):
-        """
-        Unpause the specified instance.
-        """
         pass
 
     def suspend(self, instance, callback):
-        """
-        suspend the specified instance
-        """
         pass
 
     def resume(self, instance, callback):
-        """
-        resume the specified instance
-        """
         pass
 
     def destroy(self, instance, network_info, cleanup=True):
@@ -303,25 +152,12 @@ class FakeConnection(driver.ComputeDriver):
                         (key, self.instances))
 
     def attach_volume(self, instance_name, device_path, mountpoint):
-        """Attach the disk at device_path to the instance at mountpoint"""
         return True
 
     def detach_volume(self, instance_name, mountpoint):
-        """Detach the disk attached to the instance at mountpoint"""
         return True
 
     def get_info(self, instance_name):
-        """
-        Get a block of information about the given instance.  This is returned
-        as a dictionary containing 'state': The power_state of the instance,
-        'max_mem': The maximum memory for the instance, in KiB, 'mem': The
-        current memory the instance has, in KiB, 'num_cpu': The current number
-        of virtual CPUs the instance has, 'cpu_time': The total CPU time used
-        by the instance, in nanoseconds.
-
-        This method should raise exception.NotFound if the hypervisor has no
-        knowledge of the instance
-        """
         if instance_name not in self.instances:
             raise exception.InstanceNotFound(instance_id=instance_name)
         i = self.instances[instance_name]
@@ -332,69 +168,18 @@ class FakeConnection(driver.ComputeDriver):
                 'cpu_time': 0}
 
     def get_diagnostics(self, instance_name):
-        pass
+        return {}
 
     def list_disks(self, instance_name):
-        """
-        Return the IDs of all the virtual disks attached to the specified
-        instance, as a list.  These IDs are opaque to the caller (they are
-        only useful for giving back to this layer as a parameter to
-        disk_stats).  These IDs only need to be unique for a given instance.
-
-        Note that this function takes an instance ID.
-        """
         return ['A_DISK']
 
     def list_interfaces(self, instance_name):
-        """
-        Return the IDs of all the virtual network interfaces attached to the
-        specified instance, as a list.  These IDs are opaque to the caller
-        (they are only useful for giving back to this layer as a parameter to
-        interface_stats).  These IDs only need to be unique for a given
-        instance.
-
-        Note that this function takes an instance ID.
-        """
         return ['A_VIF']
 
     def block_stats(self, instance_name, disk_id):
-        """
-        Return performance counters associated with the given disk_id on the
-        given instance_name.  These are returned as [rd_req, rd_bytes, wr_req,
-        wr_bytes, errs], where rd indicates read, wr indicates write, req is
-        the total number of I/O requests made, bytes is the total number of
-        bytes transferred, and errs is the number of requests held up due to a
-        full pipeline.
-
-        All counters are long integers.
-
-        This method is optional.  On some platforms (e.g. XenAPI) performance
-        statistics can be retrieved directly in aggregate form, without Nova
-        having to do the aggregation.  On those platforms, this method is
-        unused.
-
-        Note that this function takes an instance ID.
-        """
         return [0L, 0L, 0L, 0L, None]
 
     def interface_stats(self, instance_name, iface_id):
-        """
-        Return performance counters associated with the given iface_id on the
-        given instance_id.  These are returned as [rx_bytes, rx_packets,
-        rx_errs, rx_drop, tx_bytes, tx_packets, tx_errs, tx_drop], where rx
-        indicates receive, tx indicates transmit, bytes and packets indicate
-        the total number of bytes or packets transferred, and errs and dropped
-        is the total number of packets failed / dropped.
-
-        All counters are long integers.
-
-        This method is optional.  On some platforms (e.g. XenAPI) performance
-        statistics can be retrieved directly in aggregate form, without Nova
-        having to do the aggregation.  On those platforms, this method is
-        unused.
-
-        Note that this function takes an instance ID.
-        """
         return [0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L]
 
     def get_console_output(self, instance):
@@ -416,67 +201,12 @@ class FakeConnection(driver.ComputeDriver):
                  'password': 'fakepassword'}
 
     def refresh_security_group_rules(self, security_group_id):
-        """This method is called after a change to security groups.
-
-        All security groups and their associated rules live in the datastore,
-        and calling this method should apply the updated rules to instances
-        running the specified security group.
-
-        An error should be raised if the operation cannot complete.
-
-        """
         return True
 
     def refresh_security_group_members(self, security_group_id):
-        """This method is called when a security group is added to an instance.
-
-        This message is sent to the virtualization drivers on hosts that are
-        running an instance that belongs to a security group that has a rule
-        that references the security group identified by `security_group_id`.
-        It is the responsiblity of this method to make sure any rules
-        that authorize traffic flow with members of the security group are
-        updated and any new members can communicate, and any removed members
-        cannot.
-
-        Scenario:
-            * we are running on host 'H0' and we have an instance 'i-0'.
-            * instance 'i-0' is a member of security group 'speaks-b'
-            * group 'speaks-b' has an ingress rule that authorizes group 'b'
-            * another host 'H1' runs an instance 'i-1'
-            * instance 'i-1' is a member of security group 'b'
-
-            When 'i-1' launches or terminates we will recieve the message
-            to update members of group 'b', at which time we will make
-            any changes needed to the rules for instance 'i-0' to allow
-            or deny traffic coming from 'i-1', depending on if it is being
-            added or removed from the group.
-
-        In this scenario, 'i-1' could just as easily have been running on our
-        host 'H0' and this method would still have been called.  The point was
-        that this method isn't called on the host where instances of that
-        group are running (as is the case with
-        :method:`refresh_security_group_rules`) but is called where references
-        are made to authorizing those instances.
-
-        An error should be raised if the operation cannot complete.
-
-        """
         return True
 
     def refresh_provider_fw_rules(self):
-        """This triggers a firewall update based on database changes.
-
-        When this is called, rules have either been added or removed from the
-        datastore.  You can retrieve rules with
-        :method:`nova.db.api.provider_fw_rule_get_all`.
-
-        Provider rules take precedence over security group rules.  If an IP
-        would be allowed by a security group ingress rule, but blocked by
-        a provider rule, then packets from the IP are dropped.  This includes
-        intra-project traffic in the case of the allow_project_net_traffic
-        flag for the libvirt-derived classes.
-
-        """
         pass
 
     def update_available_resource(self, ctxt, host):