Improve documentation in ComputationAPI

Author: carver

eth/abc.py

@@ -1550,7 +1550,7 @@ def apply_message(
             message: MessageAPI,
             transaction_context: TransactionContextAPI) -> 'ComputationAPI':
         """
-        Execution of a VM message. Typically used for sub-calls.
+        Execute a VM message. This is where the VM-specific call logic exists.
         """
         ...
 
@@ -1562,7 +1562,8 @@ def apply_create_message(
             message: MessageAPI,
             transaction_context: TransactionContextAPI) -> 'ComputationAPI':
         """
-        Execution of a VM message to create a new contract. Typically used for sub-calls.
+        Execute a VM message to create a new contract. This is where the VM-specific
+        create logic exists.
         """
         ...
 
@@ -1573,7 +1574,14 @@ def apply_computation(cls,
                           message: MessageAPI,
                           transaction_context: TransactionContextAPI) -> 'ComputationAPI':
         """
-        Perform the computation that would be triggered by the VM message.
+        Execute the logic within the message: Either run the precompile, or
+        step through each opcode.  Generally, the only VM-specific logic is for
+        each opcode as it executes.
+
+        This should rarely be called directly, because it will skip over other important
+        VM-specific logic that happens before or after the execution.
+
+        Instead, prefer :meth:`~apply_message` or :meth:`~apply_create_message`.
         """
         ...
 
@@ -2509,7 +2517,17 @@ def execute_bytecode(self,
                          code_address: Address = None) -> ComputationAPI:
         """
         Execute raw bytecode in the context of the current state of
-        the virtual machine.
+        the virtual machine. Note that this skips over some of the logic
+        that would normally happen during a call. Watch out for:
+
+            - value (ether) is *not* transferred
+            - state is *not* rolled back in case of an error
+            - The target account is *not* necessarily created
+            - others...
+
+        For other potential surprises, check the implementation differences
+        between :meth:`ComputationAPI.apply_computation` and
+        :meth:`ComputationAPI.apply_message`. (depending on the VM fork)
         """
         ...