From 6b94734d1a39e4d6f68751047bd60e124a33f61a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pawe=C5=82=20Bylica?= <chfast@gmail.com>
Date: Tue, 25 Apr 2017 19:05:49 +0200
Subject: [PATCH] EVM-C: Clarify docs about result context and releasing

---
 examples/examplevm.c |  2 +-
 include/evm.h        | 27 ++++++++++++++++++++-------
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/examples/examplevm.c b/examples/examplevm.c
index 6657a93..f934072 100644
--- a/examples/examplevm.c
+++ b/examples/examplevm.c
@@ -83,7 +83,7 @@ static struct evm_result evm_execute(struct evm_instance* instance,
         ret.output_data = output_data;
         ret.output_size = address_size;
         ret.release = &free_result_output_data;
-        ret.internal_memory = NULL; // We don't need another pointer.
+        ret.context = NULL; // We don't need another pointer.
         return ret;
     }
 
diff --git a/include/evm.h b/include/evm.h
index 932fb6c..abef3f9 100644
--- a/include/evm.h
+++ b/include/evm.h
@@ -106,20 +106,33 @@ struct evm_result {
     /// The size of the output data.
     size_t output_size;
 
-    /// The pointer to the result release implementation.
+    /// The pointer to a function releasing all resources associated with
+    /// the result object.
     ///
-    /// This function pointer may be set by the EVM implementation and must be
-    /// used by the user to release memory associated with the result object.
-    /// In case it is NULL the user does not have to release any resources.
+    /// This function pointer is optional (MAY be NULL) and MAY be set by
+    /// the EVM implementation. If set it MUST be used by the user to
+    /// release memory and other resources associated with the result object.
+    /// After the result resources are released the result object
+    /// MUST NOT be used any more.
+    ///
+    /// The suggested code pattern for releasing EVM results:
+    /// @code
+    /// struct evm_result result = ...;
+    /// if (result.release)
+    ///     result.release(&result);
+    /// @endcode
     ///
     /// @note
     /// It works similarly to C++ virtual destructor. Attaching the release
     /// function to the result itself allows EVM composition.
     evm_release_result_fn release;
 
-    /// The pointer to EVM-owned memory. For EVM internal use.
-    /// @see output_data.
-    void* internal_memory;
+    /// The optional pointer to an internal EVM context.
+    ///
+    /// This field MAY be used by _EVM implementations_ to store additional
+    /// result context (e.g. memory buffers). The pointer value MUST NOT
+    /// be accessed nor changed by EVM users.
+    void* context;
 };
 
 /// The query callback key.