Merge pull request #248 from ethereum/docs-cpp

docs: Include documentation for C++ API
2019-04-25 08:36:20 +02:00 · 2019-04-25 08:36:20 +02:00 · 15048cab49
parent 9a1141ef51 bc7f9ea1ef
commit 15048cab49
9 changed files with 96 additions and 28 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -4,9 +4,10 @@

 - Added: [[#216](https://github.com/ethereum/evmc/pull/216)]
  CMake option `EVMC_TEST_TOOLS` to build evmc-vmtester without bothering with internal unit tests.
- Added: [[#217](https://github.com/ethereum/evmc/pull/217)]
-  The `evmc::host` C++ wrapper for EVMC host context and interface
-  to be used by VM implementations.
+- Added:
+  [[#217](https://github.com/ethereum/evmc/pull/217)]
+  [[#226](https://github.com/ethereum/evmc/pull/226)]
+  The full C++ EVMC API for both VM and Host implementations.
 - Added: [[#201](https://github.com/ethereum/evmc/pull/201), [#202](https://github.com/ethereum/evmc/pull/202), [#233](https://github.com/ethereum/evmc/pull/233)]
  Initial and rough bindings for Rust.  It is possible to implement an
  EVMC VM in Rust utilising some helpers.
@ -14,6 +15,8 @@
  [[#230](https://github.com/ethereum/evmc/pull/230)]
  [[#232](https://github.com/ethereum/evmc/pull/232)]
  Handling of DLL loading errors greatly improved by `evmc_last_error_msg()` function.
+- Changed: [[#195](https://github.com/ethereum/evmc/pull/195)]
+  The minimum supported GCC version is 6 (bumped from undocumented version 4.8).
 - Changed: [[#197](https://github.com/ethereum/evmc/pull/197)]
  Go bindings improved by introduction of the `TxContext` struct.
 - Changed:
--- a/4
+++ b/4
@ -100,7 +100,7 @@ WARN_LOGFILE           =
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT                  = \
-    include/evmc/evmc.h include/evmc/helpers.h include/evmc/helpers.hpp include/evmc/loader.h include/evmc/utils.h include/evmc/instructions.h \
+    include/evmc/ \
    docs/ \
    examples/example_vm.c
 INPUT_ENCODING         = UTF-8
@ -109,7 +109,7 @@ RECURSIVE              = NO
 EXCLUDE                =
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       =
-EXCLUDE_SYMBOLS        =
+EXCLUDE_SYMBOLS        = internal std
 EXAMPLE_PATH           =
 EXAMPLE_PATTERNS       =
 EXAMPLE_RECURSIVE      = NO
--- a/README.md
+++ b/README.md
@ -19,15 +19,13 @@ Please visit the [documentation].
 ### Languages support

 | Language                | Supported Versions  | Supported Compilers
-| ----------------------- | ------------------- | -------------------
-| **C**                   | C90, C99, C11       | GCC 6+, clang 3.8+
-| **C++** _(helpers)_[^1] | C++11, C++14, C++17 | GCC 6+, clang 3.8+
+| ----------------------- | ------------------- | ------------------------------
+| **C**                   | C90, C99, C11       | GCC 6+, clang 3.8+, MSVC 2015+
+| **C++**                 | C++11, C++14, C++17 | GCC 6+, clang 3.8+, MSVC 2015+
 | **Go** _(bindings)_     | 1.9 - 1.12          |
-| **Rust** _(bindings)_[^2] | 2018 edition      | 1.31.0 and newer
+| **Rust** _(bindings)_[^1] | 2018 edition      | 1.31.0 and newer

-[^1]: C++ support is provided by C headers and some optional C++ helpers.
-
-[^2]: Rust support is limited and not complete yet.
+[^1]: Rust support is limited and not complete yet.

 ## Related projects

--- a/docs/EVMC.md
+++ b/docs/EVMC.md
@ -35,6 +35,8 @@ API changes are allowed when required to fix a broken feature.

 - [EVMC](@ref EVMC)
   – the main component that defines API for VMs and Clients (Hosts).
+- [EVMC C++ API](@ref evmc)
+   – the wrappers and bindings for C++.
 - [EVMC Loader](@ref loader)
   – the library for loading VMs implemented as Dynamically Loaded Libraries (DLLs, shared objects).
 - [EVMC Helpers](@ref helpers)
--- a/docs/custom.dox
+++ b/docs/custom.dox
@ -0,0 +1,29 @@
+/**
+ * @defgroup cpp EVMC C++
+ * @copydoc evmc
+ */
+
+/**
+ * @file evmc.h
+ * @copydoc EVMC
+ */
+
+/**
+ * @file evmc.hpp
+ * @copydoc cpp
+ */
+
+/**
+ * @file helpers.h
+ * @copydoc helpers
+ */
+
+/**
+ * @file instructions.h
+ * @copydoc instructions
+ */
+
+/**
+ * @file loader.h
+ * @copydoc loader
+ */
--- a/include/evmc/evmc.h
+++ b/include/evmc/evmc.h
@ -653,12 +653,11 @@ struct evmc_host_interface
 /**
 * Execution context managed by the Host.
 *
- *  The Host MUST pass the pointer to the execution context to
- *  ::evmc_execute_fn. The EVM MUST pass the same pointer back to the Host in
- *  every callback function.
- *  The context MUST contain at least the function table defining the context
- *  callback interface.
- *  Optionally, The Host MAY include in the context additional data.
+ * The Host MUST pass the pointer to the execution context to ::evmc_execute_fn.
+ * The VM MUST pass the same pointer back to the Host in every callback function.
+ * The context MUST contain at least the function table defining
+ * the context callback interface.
+ * Optionally, the Host MAY include in the context additional data.
 */
 struct evmc_context
 {
@ -912,15 +911,15 @@ typedef void (*evmc_set_tracer_fn)(struct evmc_instance* instance,
 /**
 * The EVM instance.
 *
- *  Defines the base struct of the EVM implementation.
+ * Defines the base struct of the VM implementation.
 */
 struct evmc_instance
 {
    /**
-     *  EVMC ABI version implemented by the EVM instance.
+     * EVMC ABI version implemented by the VM instance.
     *
-     *  Used to detect ABI incompatibilities. The EVMC ABI version
-     *  represented by this file is in ::EVMC_ABI_VERSION.
+     * Can be used to detect ABI incompatibilities.
+     * The EVMC ABI version represented by this file is in ::EVMC_ABI_VERSION.
     */
    const int abi_version;

--- a/include/evmc/evmc.hpp
+++ b/include/evmc/evmc.hpp
@ -3,28 +3,34 @@
 * Licensed under the Apache License, Version 2.0.
 */

-/// @file
-/// EVMC C++ API - wrappers and bindings for C++.
-
 #include <evmc/evmc.h>
 #include <evmc/helpers.h>

 #include <initializer_list>
 #include <utility>

+/// EVMC C++ API - wrappers and bindings for C++
+/// @ingroup cpp
 namespace evmc
 {
+/// @copydoc evmc_result
+///
+/// This is a RAII wrapper for evmc_result and objects of this type
+/// automatically release attached resources.
 class result : public evmc_result
 {
 public:
+    /// Converting constructor from raw evmc_result.
    explicit result(evmc_result const& res) noexcept : evmc_result{res} {}

+    /// Destructor responsible for automatically releasing attached resources.
    ~result() noexcept
    {
        if (release)
            release(this);
    }

+    /// Move constructor.
    result(result&& other) noexcept : evmc_result{other}
    {
        // Disable releaser of the rvalue object.
@ -33,6 +39,7 @@ public:

    result(result const&) = delete;

+    /// Move-and-swap assignment operator.
    result& operator=(result other) noexcept
    {
        std::swap(*this, other);
@ -40,12 +47,21 @@ public:
    }
 };

+/// @copybrief evmc_instance
+///
+/// This is a RAII wrapper for evmc_instance and objects of this type
+/// automatically destroys the VM instance.
 class vm
 {
 public:
+    /// Converting constructor from evmc_instance.
    explicit vm(evmc_instance* instance) noexcept : m_instance{instance} {}
+
+    /// Destructor responsible for automatically destroying the VM instance.
    ~vm() noexcept { m_instance->destroy(m_instance); }

+    /// The constructor that captures a VM instance and configures the instance
+    /// with provided list of options.
    vm(evmc_instance* instance,
       std::initializer_list<std::pair<const char*, const char*>> options) noexcept
      : m_instance{instance}
@ -54,17 +70,22 @@ public:
            set_option(option.first, option.second);
    }

+    /// Checks whenever the VM instance is ABI compatible with the current EVMC API.
    bool is_abi_compatible() const noexcept { return m_instance->abi_version == EVMC_ABI_VERSION; }

+    /// @copydoc evmc_instance::name
    char const* name() const noexcept { return m_instance->name; }

+    /// @copydoc evmc_instance::version
    char const* version() const noexcept { return m_instance->version; }

+    /// @copydoc evmc_set_option()
    evmc_set_option_result set_option(const char name[], const char value[]) noexcept
    {
        return evmc_set_option(m_instance, name, value);
    }

+    /// @copydoc evmc_execute()
    result execute(evmc_context& ctx,
                   evmc_revision rev,
                   const evmc_message& msg,
@ -78,41 +99,53 @@ private:
    evmc_instance* const m_instance = nullptr;
 };

-
+/// The EVMC Host interface
 class HostInterface
 {
 public:
    virtual ~HostInterface() noexcept = default;

+    /// @copydoc evmc_host_interface::account_exists
    virtual bool account_exists(const evmc_address& addr) noexcept = 0;

+    /// @copydoc evmc_host_interface::get_storage
    virtual evmc_bytes32 get_storage(const evmc_address& addr,
                                     const evmc_bytes32& key) noexcept = 0;

+    /// @copydoc evmc_host_interface::set_storage
    virtual evmc_storage_status set_storage(const evmc_address& addr,
                                            const evmc_bytes32& key,
                                            const evmc_bytes32& value) noexcept = 0;

+    /// @copydoc evmc_host_interface::get_balance
    virtual evmc_uint256be get_balance(const evmc_address& addr) noexcept = 0;

+    /// @copydoc evmc_host_interface::get_code_size
    virtual size_t get_code_size(const evmc_address& addr) noexcept = 0;

+    /// @copydoc evmc_host_interface::get_code_hash
    virtual evmc_bytes32 get_code_hash(const evmc_address& addr) noexcept = 0;

+    /// @copydoc evmc_host_interface::copy_code
    virtual size_t copy_code(const evmc_address& addr,
                             size_t code_offset,
                             uint8_t* buffer_data,
                             size_t buffer_size) noexcept = 0;

+    /// @copydoc evmc_host_interface::selfdestruct
    virtual void selfdestruct(const evmc_address& addr,
                              const evmc_address& beneficiary) noexcept = 0;

+    /// @copydoc evmc_host_interface::call
    virtual result call(const evmc_message& msg) noexcept = 0;

+    /// @copydoc evmc_host_interface::get_tx_context
    virtual evmc_tx_context get_tx_context() noexcept = 0;

+    /// @copydoc evmc_host_interface::get_block_hash
    virtual evmc_bytes32 get_block_hash(int64_t block_number) noexcept = 0;

+    /// @copydoc evmc_host_interface::emit_log
    virtual void emit_log(const evmc_address& addr,
                          const uint8_t* data,
                          size_t data_size,
@ -130,6 +163,7 @@ class HostContext : public HostInterface
    evmc_tx_context tx_context = {};

 public:
+    /// Implicit converting constructor from evmc_context.
    HostContext(evmc_context* context) noexcept : context{context} {}  // NOLINT

    bool account_exists(const evmc_address& address) noexcept final
@ -182,7 +216,7 @@ public:
        return result{context->host->call(context, &message)};
    }

-    /// Gets the transaction and block context from the Host.
+    /// @copydoc HostInterface::get_tx_context()
    ///
    /// The implementation caches the received transaction context
    /// by assuming that the block timestamp should never be zero.
--- a/include/evmc/helpers.h
+++ b/include/evmc/helpers.h
@ -6,7 +6,7 @@
 /**
 * EVMC Helpers
 *
- * A collection of helper functions for invoking a VM instance methods.
+ * A collection of C helper functions for invoking a VM instance methods.
 * These are convenient for languages where invoking function pointers
 * is "ugly" or impossible (such as Go).
 *
--- a/include/evmc/utils.h
+++ b/include/evmc/utils.h
@ -6,6 +6,9 @@
 #pragma once

 /**
+ * @file
+ * A collection of helper macros to handle some non-portable features of C/C++ compilers.
+ *
 * @addtogroup helpers
 * @{
 */