Add docstring in get_rsapi_state()

Add improved documentation on how the API state is derived
based on the internal state of the VirtualMachine instance.

logic/utils.py

@@ -25,9 +25,26 @@ def id_from_instance_name(name):
 
     return int(ns)
 
-
 def get_rsapi_state(vm):
-    """Returns the RSAPI state for a virtual machine"""
+    """Returns the API state for a virtual machine
+    
+    The API state for an instance of VirtualMachine is derived as follows:
+
+    * If the deleted flag has been set, it is "DELETED".
+    * Otherwise, it is a mapping of the last state reported by Ganeti
+      (vm.operstate) through the RSAPI_STATE_FROM_OPER_STATE dictionary.
+      
+      The last state reported by Ganeti is set whenever Ganeti reports
+      successful completion of an operation. If Ganeti says an OP_INSTANCE_STARTUP
+      operation succeeded, vm.operstate is set to "STARTED".
+
+    * To support any transitive states defined by the API (only REBOOT for the time
+      being) this mapping is amended with information reported by Ganeti regarding
+      any outstanding operation. If an OP_INSTANCE_STARTUP had succeeded previously
+      and an OP_INSTANCE_REBOOT has been reported as in progress, the API state is
+      "REBOOT".
+
+    """
     try:
         r = VirtualMachine.RSAPI_STATE_FROM_OPER_STATE[vm.operstate]
     except KeyError: