docs: Include documentation for C++ API

Doxyfile

@@ -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/evmc.h include/evmc/evmc.hpp include/evmc/helpers.h include/evmc/helpers.hpp include/evmc/loader.h include/evmc/utils.h include/evmc/instructions.h \
     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
 EXAMPLE_PATH           =
 EXAMPLE_PATTERNS       =
 EXAMPLE_RECURSIVE      = NO

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
+ * The Host MUST pass the pointer to the execution context to ::evmc_execute_fn.
- *  ::evmc_execute_fn. The EVM MUST pass the same pointer back to the Host in
+ * The VM MUST pass the same pointer back to the Host in every callback function.
- *  every callback function.
+ * The context MUST contain at least the function table defining
- *  The context MUST contain at least the function table defining the context
+ * the context callback interface.
- *  callback interface.
+ * Optionally, the Host MAY include in the context additional data.
- *  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
+     * Can be used to detect ABI incompatibilities.
-     *  represented by this file is in ::EVMC_ABI_VERSION.
+     * The EVMC ABI version represented by this file is in ::EVMC_ABI_VERSION.
      */
     const int abi_version;
 

include/evmc/evmc.hpp

@@ -3,28 +3,37 @@
  * 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>
 
+/// @defgroup cpp EVMC C++
+/// @copydoc evmc
+/// @{
+
+/// EVMC C++ API - wrappers and bindings for C++
 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 +42,7 @@ public:
 
     result(result const&) = delete;
 
+    /// Move-and-swap assignment operator.
     result& operator=(result other) noexcept
     {
         std::swap(*this, other);
@@ -40,12 +50,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 +73,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 +102,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 +166,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 +219,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.
@@ -297,3 +334,5 @@ constexpr evmc_host_interface interface{
 inline Host::Host() noexcept : evmc_context{&internal::interface} {}
 
 }  // namespace evmc
+
+/// @}