Merge pull request #58 from OffchainLabs/document-modules

Document modules and `hostio` feature flag

Cargo.toml

@@ -3,7 +3,7 @@ members = ["stylus-sdk", "stylus-proc"]
 resolver = "2"
 
 [workspace.package]
-version = "0.2.3"
+version = "0.2.4"
 edition = "2021"
 authors = ["Offchain Labs"]
 license = "MIT OR Apache-2.0"

stylus-proc/Cargo.toml

@@ -24,6 +24,10 @@ quote.workspace = true
 
 [features]
 export-abi = []
+storage-cache = []
+
+[package.metadata.docs.rs]
+all-features = true
 
 [lib]
 proc-macro = true

stylus-proc/src/methods/entrypoint.rs

@@ -59,6 +59,14 @@ pub fn entrypoint(attr: TokenStream, input: TokenStream) -> TokenStream {
         _ => error!(input, "not a struct or fn"),
     };
 
+    #[cfg(feature = "storage-cache")]
+    let flush_cache = quote! {
+        stylus_sdk::storage::StorageCache::flush();
+    };
+
+    #[cfg(not(feature = "storage-cache"))]
+    let flush_cache = quote! {};
+
     output.extend(quote! {
         #[no_mangle]
         pub unsafe fn mark_used() {
@@ -80,7 +88,7 @@ pub fn entrypoint(attr: TokenStream, input: TokenStream) -> TokenStream {
                 Ok(data) => (data, 0),
                 Err(data) => (data, 1),
             };
-            stylus_sdk::storage::StorageCache::flush();
+            #flush_cache
             stylus_sdk::contract::output(&data);
             status
         }

stylus-sdk/Cargo.toml

@@ -38,5 +38,6 @@ all-features = true
 default = ["storage-cache"]
 export-abi = ["debug", "regex", "stylus-proc/export-abi"]
 debug = []
-storage-cache = ["fnv"]
 docs = []
+hostio = []
+storage-cache = ["fnv", "stylus-proc/storage-cache"]

stylus-sdk/src/abi/bytes.rs

@@ -12,7 +12,7 @@ use core::ops::{Deref, DerefMut};
 
 /// Represents a [`bytes`] in Solidity.
 ///
-/// [`bytes`]: https://docs.soliditylang.org/en/v0.8.21/types.html#bytes-and-string-as-arrays
+/// [`bytes`]: https://docs.soliditylang.org/en/latest/types.html#bytes-and-string-as-arrays
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Bytes(pub Vec<u8>);
 
@@ -54,6 +54,7 @@ impl AsMut<[u8]> for Bytes {
     }
 }
 
+/// Provides a corresponding [`SolType`] for an abi [`Bytes`].
 pub struct BytesSolType;
 
 impl SolType for BytesSolType {

stylus-sdk/src/abi/const_string.rs

@@ -1,18 +1,23 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! Provides [`ConstString`], a mechanism for string operations in `const` contexts.
+
 use core::{
     fmt::{Debug, Display},
     ops::Deref,
 };
 
+/// Maximum length of a [`ConstString`] in bytes.
 pub const MAX_CONST_STRING_LENGTH: usize = 1024;
 
+/// Represents a string with a bounded length at compile time.
+/// This allows something approximating string operations in `const` contexts.
 #[derive(Clone)]
 pub struct ConstString {
     /// The signature's text encoding. Must be valid UTF-8.
-    /// Note: this representation allows something approximating string manipulation to be const.
     data: [u8; MAX_CONST_STRING_LENGTH],
+    /// The length of the string in bytes.
     len: usize,
 }
 

stylus-sdk/src/abi/export.rs

@@ -1,6 +1,13 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! Traits for exporting Solidity interfaces.
+//!
+//! The contents of this module are imported when the `export-abi` feature flag is enabled,
+//! which happens automatically during [`cargo stylus export-abi`][cargo].
+//!
+//! [cargo]: https://github.com/OffchainLabs/cargo-stylus#exporting-solidity-abis
+
 use core::{fmt, marker::PhantomData};
 use lazy_static::lazy_static;
 use regex::Regex;

stylus-sdk/src/abi/fixed_bytes.rs

@@ -10,6 +10,11 @@ use alloy_sol_types::{
     Encodable, SolType, Word,
 };
 
+/// Provides a corresponding [`SolType`] for [`FixedBytes`].
+///
+/// This type will be removed after an upcoming [`FixedBytes refactor`][refactor] in Alloy.
+///
+/// [refactor]: https://github.com/alloy-rs/core/issues/259
 pub struct FixedBytesSolType<const N: usize>;
 
 impl<const N: usize> FixedBytesSolType<N> {

stylus-sdk/src/abi/mod.rs

@@ -1,6 +1,19 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! Solidity ABIs for Rust types.
+//!
+//! Alloy provides a 1-way mapping of Solidity types to Rust ones via [`SolType`].
+//! This module provides the inverse mapping, forming a bijective, 2-way relationship between Rust and Solidity.
+//!
+//! This allows the [`prelude`][prelude] macros to generate method selectors, export
+//! Solidity interfaces, and otherwise facilitate interop between Rust and Solidity contracts.
+//!
+//! Notably, the SDK treats `Vec<u8>` as a Solidity `uint8[]`.
+//! For a Solidity `bytes`, see [`Bytes`].
+//!
+//! [prelude]: crate::prelude
+
 use crate::{storage::TopLevelStorage, ArbResult};
 use alloy_sol_types::SolType;
 use core::borrow::BorrowMut;

stylus-sdk/src/block.rs

@@ -1,6 +1,17 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! VM affordances for inspecting the current block.
+//!
+//! See also [`contract`](crate::contract), [`crypto`](crate::crypto), [`evm`](crate::evm),
+//! [`msg`](crate::msg), and [`tx`](crate::tx).
+//!
+//! ```no_run
+//! use stylus_sdk::block;
+//!
+//! let number = block::number();
+//! ```
+
 use crate::hostio::{self, wrap_hostio};
 use alloy_primitives::{Address, B256, U256};
 

stylus-sdk/src/call/mod.rs

@@ -1,6 +1,8 @@
 // Copyright 2022-2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! Call other contracts.
+
 use crate::storage::TopLevelStorage;
 use alloy_primitives::{Address, U256};
 use core::sync::atomic::{AtomicBool, Ordering};

stylus-sdk/src/contract.rs

@@ -1,6 +1,17 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! VM affordances for inspecting the contract itself.
+//!
+//! See also [`block`](crate::block), [`crypto`](crate::crypto), [`evm`](crate::evm),
+//! [`msg`](crate::msg), and [`tx`](crate::tx).
+//!
+//! ```no_run
+//! use stylus_sdk::contract;
+//!
+//! let balance = contract::balance();
+//! ```
+
 use crate::{
     hostio::{self, wrap_hostio},
     types::AddressVM,

stylus-sdk/src/crypto.rs

@@ -1,6 +1,19 @@
 // Copyright 2022-2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! VM-accelerated cryptography.
+//!
+//! See also [`block`](crate::block), [`contract`](crate::contract), [`evm`](crate::evm),
+//! [`msg`](crate::msg), and [`tx`](crate::tx).
+//!
+//! ```no_run
+//! use stylus_sdk::crypto;
+//! use stylus_sdk::alloy_primitives::address;
+//!
+//! let preimage = address!("361594F5429D23ECE0A88E4fBE529E1c49D524d8");
+//! let hash = crypto::keccak(&preimage);
+//! ```
+
 use alloy_primitives::B256;
 
 /// Efficiently computes the [`keccak256`] hash of the given preimage.

stylus-sdk/src/debug.rs

@@ -1,6 +1,16 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! Debug-only items for printing to the console.
+//!
+//! ```no_run
+//! use stylus_sdk::console;
+//! use stylus_sdk::alloy_primitives::address;
+//!
+//! let arbinaut = address!("361594F5429D23ECE0A88E4fBE529E1c49D524d8");
+//! console!("Gm {}", arbinaut); // prints nothing in production
+//! ```
+
 /// Prints a UTF-8 encoded string to the console. Only available in debug mode.
 #[cfg(feature = "debug")]
 pub fn console_log<T: AsRef<str>>(text: T) {

stylus-sdk/src/deploy/mod.rs

@@ -1,6 +1,11 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! Deploy other contracts.
+//!
+//! Currently this module only supports low-level contract creation via [`RawDeploy`],
+//! but word is being done to introduce high-level deployment patterns.
+
 pub use raw::RawDeploy;
 
 mod raw;

stylus-sdk/src/evm.rs

@@ -1,6 +1,17 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For licensing, see https://github.com/OffchainLabs/stylus-sdk-rs/blob/stylus/licenses/COPYRIGHT.md
 
+//! Affordances for the Ethereum Virtual Machine.
+//!
+//! See also [`block`](crate::block), [`contract`](crate::contract), [`crypto`](crate::crypto),
+//! [`msg`](crate::msg), and [`tx`](crate::msg).
+//!
+//! ```no_run
+//! use stylus_sdk::evm;
+//!
+//! let gas = evm::gas_left();
+//! ```
+
 use crate::hostio::{self, wrap_hostio};
 use alloy_primitives::B256;
 use alloy_sol_types::{token::WordToken, SolEvent, TopicList};