git.delta.rocks / unique-network / refs/commits / 5af31166e6db

difftreelog

doc: clarification review

Greg Zaitsev2022-08-19parent: #c89a3fa.patch.diff
in: master

3 files changed

modifiedcrates/evm-coder/procedural/src/solidity_interface.rsdiffbeforeafterboth
--- a/crates/evm-coder/procedural/src/solidity_interface.rs
+++ b/crates/evm-coder/procedural/src/solidity_interface.rs
@@ -16,6 +16,10 @@
 
 #![allow(dead_code)]
 
+// NOTE: In order to understand this Rust macro better, first read this chapter
+// about Procedural Macros in Rust book:
+// https://doc.rust-lang.org/reference/procedural-macros.html
+
 use quote::{quote, ToTokens};
 use inflector::cases;
 use std::fmt::Write;
@@ -485,6 +489,8 @@
 	Pure,
 }
 
+/// Group all keywords for this macro. Usage example:
+/// #[solidity_interface(name = "B", inline_is(A))]
 mod kw {
 	syn::custom_keyword!(weight);
 
@@ -498,6 +504,7 @@
 	syn::custom_keyword!(rename_selector);
 }
 
+/// Rust methods are parsed into this structure when Solidity code is generated
 struct Method {
 	name: Ident,
 	camel_name: String,
modifiedcrates/evm-coder/src/execution.rsdiffbeforeafterboth
before · crates/evm-coder/src/execution.rs
1// Copyright 2019-2022 Unique Network (Gibraltar) Ltd.2// This file is part of Unique Network.34// Unique Network is free software: you can redistribute it and/or modify5// it under the terms of the GNU General Public License as published by6// the Free Software Foundation, either version 3 of the License, or7// (at your option) any later version.89// Unique Network is distributed in the hope that it will be useful,10// but WITHOUT ANY WARRANTY; without even the implied warranty of11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the12// GNU General Public License for more details.1314// You should have received a copy of the GNU General Public License15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.1617//! Contract execution related types1819#[cfg(not(feature = "std"))]20use alloc::string::{String, ToString};21use evm_core::{ExitError, ExitFatal};22#[cfg(feature = "std")]23use std::string::{String, ToString};2425use crate::Weight;2627/// Execution error, should be convertible between EVM and Substrate.28#[derive(Debug, Clone)]29pub enum Error {30	/// Non-fatal contract error occured31	Revert(String),32	/// EVM fatal error33	Fatal(ExitFatal),34	/// EVM normal error35	Error(ExitError),36}3738impl<E> From<E> for Error39where40	E: ToString,41{42	fn from(e: E) -> Self {43		Self::Revert(e.to_string())44	}45}4647/// To be used in [`crate::solidity_interface`] implementation.48pub type Result<T> = core::result::Result<T, Error>;4950/// Static information collected from [`crate::weight`].51pub struct DispatchInfo {52	/// Statically predicted call weight53	pub weight: Weight,54}5556impl From<Weight> for DispatchInfo {57	fn from(weight: Weight) -> Self {58		Self { weight }59	}60}61impl From<()> for DispatchInfo {62	fn from(_: ()) -> Self {63		Self { weight: 0 }64	}65}6667/// Weight information that is only available post dispatch.68/// Note: This can only be used to reduce the weight or fee, not increase it.69#[derive(Default, Clone)]70pub struct PostDispatchInfo {71	/// Actual weight consumed by call72	actual_weight: Option<Weight>,73}7475impl PostDispatchInfo {76	/// Calculate amount to be returned back to user77	pub fn calc_unspent(&self, info: &DispatchInfo) -> Weight {78		info.weight - self.calc_actual_weight(info)79	}8081	/// Calculate actual cansumed weight, saturating to weight reported82	/// pre-dispatch83	pub fn calc_actual_weight(&self, info: &DispatchInfo) -> Weight {84		if let Some(actual_weight) = self.actual_weight {85			actual_weight.min(info.weight)86		} else {87			info.weight88		}89	}90}9192/// Wrapper for PostDispatchInfo and any user-provided data93#[derive(Clone)]94pub struct WithPostDispatchInfo<T> {95	/// User provided data96	pub data: T,97	/// Info known after dispatch98	pub post_info: PostDispatchInfo,99}100101impl<T> From<T> for WithPostDispatchInfo<T> {102	fn from(data: T) -> Self {103		Self {104			data,105			post_info: Default::default(),106		}107	}108}109110/// Return type of items in [`crate::solidity_interface`] definition111pub type ResultWithPostInfo<T> =112	core::result::Result<WithPostDispatchInfo<T>, WithPostDispatchInfo<Error>>;
modifiedcrates/evm-coder/src/lib.rsdiffbeforeafterboth
--- a/crates/evm-coder/src/lib.rs
+++ b/crates/evm-coder/src/lib.rs
@@ -34,17 +34,18 @@
 ///
 /// `#[solidity_interface(name, is, inline_is, events)]`
 /// - *name* - used in generated code, and for Call enum name
-/// - *is* - used to provide call inheritance, not found methods will be delegated to all contracts
-/// specified in is/inline_is
-/// - *inline_is* - same as is, but selectors for passed contracts will be used by derived ERC165
-/// implementation
+/// - *is* - used to provide inheritance in Solidity
+/// - *inline_is* - same as `is`, but ERC165::SupportsInterface will work differently: For `is` SupportsInterface(A) will return true
+///   if A is one of the interfaces the contract is inherited from (e.g. B is created as `is(A)`). If B is created as `inline_is(A)`
+///   SupportsInterface(A) will internally create a new interface that combines all methods of A and B, so SupportsInterface(A) will return
+///   false.
 ///
 /// `#[weight(value)]`
 /// Can be added to every method of impl block, used for deriving [`crate::Weighted`], which
 /// is used by substrate bridge.
 /// - *value*: expression, which evaluates to weight required to call this method.
 /// This expression can use call arguments to calculate non-constant execution time.
-/// This expression should evaluate faster than actual execution does, and may provide worser case
+/// This expression should evaluate faster than actual execution does, and may provide worse case
 /// than one is called.
 ///
 /// `#[solidity_interface(rename_selector)]`