Enhance documentation

Doxyfile

@@ -99,7 +99,9 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = include/evmc/
+INPUT                  = \
+    include/evmc/evmc.h include/evmc/loader.h include/evmc/helpers.h include/evmc/utils.h include/evmc/instructions.h \
+    docs/
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO
@@ -176,7 +178,7 @@ QHG_LOCATION           =
 GENERATE_ECLIPSEHELP   = NO
 ECLIPSE_DOC_ID         = org.doxygen.Project
 DISABLE_INDEX          = NO
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 ENUM_VALUES_PER_LINE   = 4
 TREEVIEW_WIDTH         = 250
 EXT_LINKS_IN_WINDOW    = NO

README.md

@@ -6,7 +6,7 @@
 > Ethereum Client-VM Connector API
 
 The EVMC is the low-level ABI between Ethereum Virtual Machines (EVMs) and 
-Ethereum Clients. On the EVM-side it supports classic EVM1 and [eWASM].
+Ethereum Clients. On the EVM side it supports classic EVM1 and [eWASM].
 On the Client-side it defines the interface for EVM implementations 
 to access Ethereum environment and state.
 
@@ -49,7 +49,7 @@ Licensed under the [MIT License](LICENSE.md).
 [@axic]: https://github.com/axic
 [@chfast]: https://github.com/chfast
 [documentation]: https://ethereum.github.io/evmc
-[eWASM]: https://github.com/ewasm/design#ethereum-flavored-webassembly-ewasm-design
+[eWASM]: https://github.com/ewasm/design
 [evmjit]: https://github.com/ethereum/evmjit
 [Hera]: https://github.com/ewasm/hera
 [Gitter]: https://gitter.im/ethereum/evmc

appveyor.yml

@@ -2,6 +2,7 @@ version: "{build}"
 branches:
   only:
   - master
+  - /release\/.*/
   - appveyor
   - hunter
 configuration:

docs/EVMC.md

@@ -0,0 +1,51 @@
+# EVMC – Ethereum Client-VM Connector API {#mainpage}
+
+The EVMC is the low-level ABI between Ethereum Virtual Machines (EVMs) and 
+Ethereum Clients. On the EVM-side it supports classic EVM1 and [eWASM].
+On the Client-side it defines the interface for EVM implementations 
+to access Ethereum environment and state.
+
+
+## Modules
+
+- [EVMC](@ref EVMC) 
+   – the main component that defines API for VMs and Clients (Hosts).
+- [EVMC Loader](@ref loader)
+   – the library for loading VMs implemented as Dynamically Loaded Libraries (DLLs, shared objects). 
+- [EVMC Helpers](@ref helpers)
+   – a collection of utility functions for easier integration with EVMC.
+- [EVM Instructions](@ref instructions) 
+   – the library with collection of metrics for EVM1 instruction set.
+
+
+[eWASM]: https://github.com/ewasm/design
+
+
+@addtogroup EVMC
+
+## Terms
+
+1. **VM** – An Ethereum Virtual Machine instance/implementation.
+2. **Host** – An entity controlling the VM. 
+   The Host requests code execution and responses to VM queries by callback 
+   functions. This usually represents an Ethereum Client.
+
+
+## Responsibilities
+
+### VM
+
+- Executes the code (obviously).
+- Calculates the running gas cost and manages the gas counter except the refund
+  counter.
+- Controls the call depth, including the exceptional termination of execution
+  in case the maximum depth is reached.
+
+
+### Host
+
+- Provides access to State.
+- Creates new accounts (with code being a result of VM execution).
+- Handles refunds entirely.
+- Manages the set of precompiled contracts and handles execution of messages
+  coming to them.

include/evmc/evmc.h

@@ -5,23 +5,6 @@
  * Copyright 2018 Alex Beregszaszi, Pawel Bylica.
  * Licensed under the MIT License. See the LICENSE file.
  *
- * ## High level design rules
- *
- * 1. Pass function arguments and results by value.
- *    This rule comes from modern C++ and tries to avoid costly alias analysis
- *    needed for optimization. As the result we have a lots of complex structs
- *    and unions. And variable sized arrays of bytes cannot be passed by copy.
- * 2. The EVM operates on integers so it prefers values to be host-endian.
- *    On the other hand, LLVM can generate good code for byte swaping.
- *    The interface also tries to match host application "natural" endianess.
- *    I would like to know what endianess you use and where.
- *
- * ## Terms
- *
- * 1. EVM  -- an Ethereum Virtual Machine instance/implementation.
- * 2. Host -- an entity controlling the EVM. The Host requests code execution
- *            and responses to EVM queries by callback functions.
- *
  * @defgroup EVMC EVMC
  * @{
  */

include/evmc/utils.h

@@ -5,14 +5,29 @@
 
 #pragma once
 
+/**
+ * @addtogroup helpers
+ * @{
+ */
+
+/**
+ * @def EVMC_EXPORT
+ * Marks a function to be exported from a shared library.
+ */
 #if defined _MSC_VER || defined __MINGW32__
 #define EVMC_EXPORT __declspec(dllexport)
 #else
 #define EVMC_EXPORT __attribute__((visibility("default")))
 #endif
 
+/**
+ * @def EVMC_NOEXCEPT
+ * Safe way of marking a function with `noexcept` C++ specifier.
+ */
 #if __cplusplus
 #define EVMC_NOEXCEPT noexcept
 #else
 #define EVMC_NOEXCEPT
 #endif
+
+/** @} */