Merge pull request #62 from ewasm/doc-cleanup

Clean up documentation (rustdoc)

Author: axic

README.md

@@ -12,10 +12,20 @@ Add the dependency, as usual:
 [dependencies]
 ewasm-api = "0.8"
 ```
+
+In your project, include the prelude:
 ```rust
-extern crate ewasm_api;
+use ewasm_api::prelude::*;
 ```
 
+Other modules are available as well, outside of the prelude. Refer to the documentation for more info.
+
+`ewasm-rust-api` builds with various feature sets:
+- `default`: Builds with `wee_alloc` as the global allocator and with the Rust standard library.
+- `qimalloc`: Builds with [qimalloc](https://github.com/wasmx/qimalloc) as the global allocator.
+- `debug`: Exposes the debugging interface.
+- `experimental`: Exposes the experimental bignum system library API.
+
 Further documentation is available [here](https://docs.rs/ewasm_api/).
 
 ## Author(s)

src/bignum.rs

@@ -1,14 +1,16 @@
 //! The bignum system library.
+use crate::types::Uint256;
 
-use super::*;
-
+/// The low-level interface to the system library. Use the wrapper functions unless you know what
+/// you're doing.
 pub mod native {
     extern "C" {
         pub fn bignum_mul256(a: *const u32, b: *const u32, ret: *const u32);
         pub fn bignum_umulmod256(a: *const u32, b: *const u32, modulo: *const u32, ret: *const u32);
     }
 }
 
+/// Unsigned 256-bit multiplication.
 pub fn mul256(a: &Uint256, b: &Uint256) -> Uint256 {
     let mut ret = Uint256::default();
 
@@ -23,6 +25,7 @@ pub fn mul256(a: &Uint256, b: &Uint256) -> Uint256 {
     ret
 }
 
+/// Unsigned 256-bit multiplication modulo n.
 pub fn umulmod256(a: &Uint256, b: &Uint256, modulo: &Uint256) -> Uint256 {
     let mut ret = Uint256::default();
 

src/convert.rs

@@ -1,3 +1,6 @@
+//! Basic type conversion traits. Unlike the native standard library, `U: From<T>` does not yet
+//! imply `T: Into<U>`.
+
 use super::*;
 
 pub trait From<T>: Sized {

src/debug.rs

@@ -1,8 +1,9 @@
 //! The native debug interface exposed to the ewasm contract. These functions are for testing
 //! purposes only. On a live VM, any bytecode trying to import these symbols will be rejected.
 
-use crate::types::*;
+use crate::types::StorageKey;
 
+/// The native interface for debugging functions.
 mod native {
     extern "C" {
         pub fn debug_print32(value: u32);
@@ -14,26 +15,32 @@ mod native {
     }
 }
 
+/// Prints an unsigned 32-bit int.
 pub fn print32(value: u32) {
     unsafe { native::debug_print32(value) }
 }
 
+/// Prints an unsigned 64-bit int.
 pub fn print64(value: u64) {
     unsafe { native::debug_print64(value) }
 }
 
+/// Prints the contents of a slice.
 pub fn print_mem(slice: &[u8]) {
     unsafe { native::debug_printMem(slice.as_ptr() as *const u32, slice.len() as u32) }
 }
 
+/// Prints the contents of a slice in hexadecimal format.
 pub fn print_mem_hex(slice: &[u8]) {
     unsafe { native::debug_printMemHex(slice.as_ptr() as *const u32, slice.len() as u32) }
 }
 
+/// Prints the value of a storage key.
 pub fn print_storage(key: &StorageKey) {
     unsafe { native::debug_printStorage(key.bytes.as_ptr() as *const u32) }
 }
 
+/// Prints the value of a storage key in hexadecimal format.
 pub fn print_storage_hex(key: &StorageKey) {
     unsafe { native::debug_printStorageHex(key.bytes.as_ptr() as *const u32) }
 }

src/lib.rs

@@ -1,24 +1,31 @@
-/// ewasm_api is a library used to interface with Ethereum's EEI in Ewasm, a set of enhancements to
-/// the Ethereum smart contract platform.
-/// ewasm_api exposes both a set of unsafe "native" functions representing the actual EEI
-/// functions, and a set of safe wrappers around them. It is recommended not to use the native
-/// functions as they do not perform bounds-checking.
-///
-/// To use ewasm_api, simply include it as a dependency in your project.
-///
-/// # Examples
-/// ```ignore
-/// extern crate ewasm_api;
-///
-/// use ewasm_api::{Hash, block_hash, finish_data};
-///
-/// #[cfg(target_arch = "wasm32")]
-/// #[no_mangle]
-/// pub extern "C" fn main() {
-///     let a: Hash = block_hash(1);
-///     finish_data(&a.bytes);
-/// }
-/// ```
+//! ewasm_api is a library used to interface with Ethereum's EEI in [Ewasm](https://github.com/ewasm/design), a set of enhancements to
+//! the Ethereum smart contract platform.
+//! ewasm_api exposes both a set of unsafe "native" functions representing the actual EEI
+//! functions, and a set of safe wrappers around them. It is recommended not to use the native
+//! functions as they do not perform bounds-checking.
+//!
+//! To use ewasm_api, simply include it as a dependency in your project.
+//! ewasm_api can be built with various feature sets:
+//! - `default`: Builds with `wee_alloc` as the global allocator and with the Rust standard
+//! library.
+//! - `qimalloc`: Builds with [qimalloc](https://github.com/wasmx/qimalloc) as the global
+//! allocator.
+//! - `debug`: Exposes the debugging interface.
+//! - `experimental`: Exposes the experimental bignum system library API.
+//!
+//! # Examples
+//! ```ignore
+//! extern crate ewasm_api;
+//!
+//! use ewasm_api::{Hash, block_hash, finish_data};
+//!
+//! #[cfg(target_arch = "wasm32")]
+//! #[no_mangle]
+//! pub extern "C" fn main() {
+//!     let a: Hash = block_hash(1);
+//!     finish_data(&a.bytes);
+//! }
+//! ```
 
 #[macro_use]
 extern crate cfg_if;

src/native.rs

@@ -1,5 +1,6 @@
-/// The native host interface exposed to the ewasm contract. Do not use these functions unless, for
-/// some reason, the safe wrapper is not flexible enough.
+//! The low-level bindings for the Ethereum Environment Interface (EEI). There is a safe set of wrappers for these functions, so use
+//! those unless you are certain you know what you're doing.
+
 extern "C" {
     pub fn ethereum_useGas(amount: u64);
     pub fn ethereum_getGasLeft() -> u64;

src/types.rs

@@ -1,3 +1,5 @@
+//! High-level types commonly used in Ethereum contracts.
+
 /// A little-endian unsigned 128-bit integer.
 #[derive(Default, Copy, Clone, Debug, PartialEq, Eq)]
 pub struct Uint128 {
@@ -22,25 +24,25 @@ pub struct Bytes32 {
     pub bytes: [u8; 32],
 }
 
-/// Type representing a value in wei.
+/// Type definition representing a value in wei.
 pub type EtherValue = Uint128;
 
-/// Type representing an address.
+/// Type definition representing an address.
 pub type Address = Bytes20;
 
-/// Type representing a storage key.
+/// Type definition representing a storage key.
 pub type StorageKey = Bytes32;
 
-/// Type representing a storage value.
+/// Type definition representing a storage value.
 pub type StorageValue = Bytes32;
 
-/// Type representing a log topic.
+/// Type definition representing a log topic.
 pub type LogTopic = Bytes32;
 
-/// Type representing a Keccak-256 or SHA-256 hash.
+/// Type definition representing a Keccak-256 or SHA-256 hash.
 pub type Hash = Bytes32;
 
-/// Type representing a block's difficulty.
+/// Type definition representing a block's difficulty.
 pub type Difficulty = Uint256;
 
 macro_rules! from_primitive_impl {

src/utils.rs

@@ -1,3 +1,7 @@
+//! General utility functions.
+
+/// Allocate an owned buffer using the global allocator.
+/// Only enabled with `std`.
 #[cfg(feature = "std")]
 pub fn unsafe_alloc_buffer(len: usize) -> Vec<u8> {
     let mut ret: Vec<u8> = Vec::with_capacity(len);