From 34d1a3ac65c8582ddb6776c4d53534399fb0bb7c Mon Sep 17 00:00:00 2001 From: akorchyn Date: Tue, 4 Feb 2025 14:13:25 +0200 Subject: [PATCH 01/14] doc: moved annotations to the near macro documentation. Created backlinks on annotations. Fixed urls --- near-sdk/src/lib.rs | 263 +++++++++++++++++++++++++------ near-sdk/src/near.rs | 147 ----------------- near-sdk/src/near_annotations.rs | 19 +++ 3 files changed, 232 insertions(+), 197 deletions(-) delete mode 100644 near-sdk/src/near.rs create mode 100644 near-sdk/src/near_annotations.rs diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 47063b567..682479657 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -24,7 +24,7 @@ //! near-sdk = "5.6.0" //! ``` //! -//! ### Example: Counter Smart Contract. For more information, see the [macro@near] documentation. +//! ### Example: Counter Smart Contract. For more information, see the [near] documentation. //! //! Below is an example of a simple counter contract that increments and retrieves a value: //! @@ -102,7 +102,7 @@ extern crate quickcheck; /// to generate the necessary code to expose `pub` methods from the contract as well /// as generating the glue code to be a valid NEAR contract. /// -/// The macro is a syntactic sugar for [macro@near_bindgen] and expands to the [macro@near_bindgen] macro invocations. +/// The macro is a syntactic sugar for [near_bindgen] and expands to the [near_bindgen] macro invocations. /// /// ## Example /// @@ -118,48 +118,6 @@ extern crate quickcheck; /// This macro will generate code to load and deserialize state if the `self` parameter is included /// as well as saving it back to state if `&mut self` is used. /// -/// # Parameter and result serialization -/// If the macro is used with Impl section, for parameter serialization, this macro will generate a struct with all of the parameters as -/// fields and derive deserialization for it. By default this will be JSON deserialized with `serde` -/// but can be overwritten by using `#[serializer(borsh)]`: -/// ```rust -/// use near_sdk::near; -/// -/// # #[near(contract_state)] -/// # struct MyContract { -/// # pub name: String, -/// # } -/// -/// #[near] -/// impl MyContract { -/// #[result_serializer(borsh)] -/// pub fn borsh_parameters(&self, #[serializer(borsh)] a: String, #[serializer(borsh)] b: String) -> String { -/// format!("{} {}", a, b) -/// } -/// } -/// ``` -/// -/// `#[near]` will also handle serializing and setting the return value of the -/// function execution based on what type is returned by the function. By default, this will be -/// done through `serde` serialized as JSON, but this can be overridden using -/// `#[result_serializer(borsh)]`: -/// ```rust -/// use near_sdk::near; -/// -/// # #[near(contract_state)] -/// # struct MyContract { -/// # pub name: String, -/// # } -/// -/// #[near] -/// impl MyContract { -/// #[result_serializer(borsh)] -/// pub fn borsh_parameters(&self) -> String { -/// self.name.clone() -/// } -/// } -/// ``` -/// /// # Usage for enum / struct /// /// If the macro is used with struct or enum, it will make the struct or enum serializable with either @@ -189,7 +147,7 @@ extern crate quickcheck; /// By passing `event_json` as an argument `near_bindgen` will generate the relevant code to format events /// according to [NEP-297](https://github.com/near/NEPs/blob/master/neps/nep-0297.md) /// -/// For parameter serialization, this macro will generate a wrapper struct to include the NEP-297 standard fields `standard` and `version +/// For parameter serialization, this macro will generate a wrapper struct to include the NEP-297 standard fields `standard` and `version` /// as well as include serialization reformatting to include the `event` and `data` fields automatically. /// The `standard` and `version` values must be included in the enum and variant declaration (see example below). /// By default this will be JSON deserialized with `serde` @@ -205,8 +163,6 @@ extern crate quickcheck; /// # pub struct Contract { /// # data: i8, /// # } -/// -/// /// #[near(event_json(standard = "nepXXX"))] /// pub enum MyEvents { /// #[event_version("1.0.0")] @@ -257,9 +213,216 @@ extern crate quickcheck; /// ))] /// struct Contract {} /// ``` +/// +/// # Sub-attributes +/// +/// ## init sub-attribute +/// +/// Contract initialization method annotation. More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/storage#initializing-the-state) +/// +/// By default, the `Default::default()` implementation of a contract will be used to initialize a contract. There can be a custom initialization function which takes parameters or performs custom logic with the following `#[init]` annotation: +/// +/// ### Basic example +/// +/// ```rust +/// use near_sdk::{log, near}; +/// +/// #[near(contract_state)] +/// #[derive(Default)] +/// pub struct Counter { +/// value: u64, +/// } +/// +/// #[near] +/// impl Counter { +/// #[init] +/// pub fn new(value: u64) -> Self { +/// log!("Custom counter initialization!"); +/// Self { value } +/// } +/// } +/// ``` +/// +/// ## payable sub-attribute +/// +/// Specifies that the method can accept NEAR tokens. More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/functions#payable-functions) +/// +/// Methods can be annotated with `#[payable]` to allow tokens to be transferred with the method invocation. For more information, see payable methods. +/// +/// To declare a function as payable, use the `#[payable]` annotation as follows: +/// +/// ### Basic example +/// +/// ```rust +///use near_sdk::near; +/// +/// #[near(contract_state)] +/// #[derive(Default)] +/// pub struct Counter { +/// val: i8, +/// } +/// +/// #[near] +/// impl Counter { +/// #[payable] +/// pub fn my_method(&mut self) { +/// //... +/// } +/// } +/// ``` +/// +/// ## private sub-attribute +/// +/// More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/functions#private-functions) +/// +/// Some methods need to be exposed to allow the contract to call a method on itself through a promise, but want to disallow any other contract to call it. +/// For this, use the `#[private]` annotation to panic when this method is called externally. See [private methods](https://docs.near.org/build/smart-contracts/anatomy/functions#private-functions) for more information. +/// +/// This annotation can be applied to any method through the following: +/// +/// ### Basic example +/// +/// ```rust +/// use near_sdk::near; +/// +/// #[near(contract_state)] +/// #[derive(Default)] +/// pub struct Counter { +/// val: u64, +/// } +/// +/// #[near] +/// impl Counter { +/// #[private] +/// pub fn my_method(&mut self) { +/// // ... +/// } +/// } +/// ``` +/// +/// ## result_serializer sub-attribute +/// +/// The macro defines the serializer for parameter and function return serialization. +/// Only one of `borsh` or `json` can be specified. +/// +/// If the macro is used with Impl section, for parameter serialization, this macro will generate a struct with all of the parameters as +/// fields and derive deserialization for it. By default this will be JSON deserialized with `serde` +/// but can be overwritten by using `#[serializer(borsh)]`: +/// ```rust +/// use near_sdk::near; +/// +/// # #[near(contract_state)] +/// # struct MyContract { +/// # pub name: String, +/// # } +/// +/// #[near] +/// impl MyContract { +/// #[result_serializer(borsh)] +/// pub fn borsh_parameters(&self, #[serializer(borsh)] a: String, #[serializer(borsh)] b: String) -> String { +/// format!("{} {}", a, b) +/// } +/// } +/// ``` +/// +/// `#[near]` will also handle serializing and setting the return value of the +/// function execution based on what type is returned by the function. By default, this will be +/// done through `serde` serialized as JSON, but this can be overridden using +/// `#[result_serializer(borsh)]`: +/// +/// ### Basic example +/// +/// ```rust +/// use near_sdk::near; +/// +/// # #[near(contract_state)] +/// # struct MyContract { +/// # pub name: String, +/// # } +/// +/// #[near] +/// impl MyContract { +/// #[result_serializer(borsh)] +/// pub fn borsh_parameters(&self) -> String { +/// self.name.clone() +/// } +/// } +/// ``` +/// +/// ## handle_result sub-attribute +/// +/// Have `#[handle_result]` to Support Result types regardless of how they're referred to +/// Function marked with `#[handle_result]` should return `Result` (where E implements [FunctionError]). +/// If you're trying to use a type alias for `Result`, try `#[handle_result(aliased)]` +/// +/// ### Basic error handling example +/// +/// This example shows how to use error handling in a contract when the types are defined in the contract. +/// This way the contract can utilize result types and panic with the type using its `ToString` implementation +/// +/// ```rust +/// use near_sdk::{near, FunctionError}; +/// +/// #[derive(FunctionError)] +/// pub enum MyError { +/// SomePanicError, +/// } +/// +/// impl std::fmt::Display for MyError { +/// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { +/// match self { +/// MyError::SomePanicError => write!(f, "Panic error message that would be displayed to the user"), +/// } +/// } +/// } +/// +/// #[near(contract_state)] +/// pub struct MyContract { +/// pub some_value: u64, +/// } +/// +/// #[near] +/// impl MyContract { +/// #[handle_result] +/// pub fn some_function(&self) -> Result<(), MyError> { +/// if self.some_value == 0 { +/// return Err(MyError::SomePanicError); +/// } +/// Ok(()) +/// } +/// } +/// ``` +/// +/// ### Basic callback function example +/// +/// This examples shows how to create a function that handles the result of a +/// cross-chain call. For more details, see [here](https://docs.near.org/build/smart-contracts/anatomy/crosscontract#callback-function) +/// +/// ```rust +/// use near_sdk::{near, AccountId, Promise, PromiseError}; +/// +/// #[near(contract_state)] +/// #[derive(Default)] +/// pub struct Counter { +/// val: u64, +/// } +/// +/// #[near] +/// impl Counter { +/// #[handle_result] +/// pub fn get_result( +/// &self, +/// account_id: AccountId, +/// #[callback_result] set_status_result: Result<(), PromiseError>, +/// ) -> Result<(), &'static str> { +/// // .. +/// Ok(()) +/// } +/// } +/// ``` pub use near_sdk_macros::near; -/// This macro is deprecated. Use [macro@near] instead. The difference between `#[near]` and `#[near_bindgen]` is that +/// This macro is deprecated. Use [near] instead. The difference between `#[near]` and `#[near_bindgen]` is that /// with `#[near_bindgen]` you have to manually add boilerplate code for structs and enums so that they become Json- and Borsh-serializable: /// ```rust /// use near_sdk::{near_bindgen, NearSchema, borsh::{BorshSerialize, BorshDeserialize}}; @@ -366,7 +529,7 @@ pub use near_sdk_macros::BorshStorageKey; pub use near_sdk_macros::PanicOnDefault; /// NOTE: This is an internal implementation for `#[near_bindgen(events(standard = ...))]` attribute. -/// Please use [macro@near] instead. +/// Please use [near] instead. /// /// This derive macro is used to inject the necessary wrapper and logic to auto format /// standard event logs and generate the `emit` function, and event version. @@ -461,7 +624,7 @@ pub use crate::utils::storage_key_impl::IntoStorageKey; pub use crate::utils::*; #[cfg(feature = "__macro-docs")] -pub mod near; +pub mod near_annotations; #[cfg(all(feature = "unit-testing", not(target_arch = "wasm32")))] pub mod test_utils; diff --git a/near-sdk/src/near.rs b/near-sdk/src/near.rs deleted file mode 100644 index 13a57426e..000000000 --- a/near-sdk/src/near.rs +++ /dev/null @@ -1,147 +0,0 @@ -//! `#[near]` and `#[near_bindgen]` documentation module -//! -//! This is not a real module; here we document the attributes that [`#[near]`](../attr.near.html) -//! and [`#[near_bindgen]`](../attr.near_bindgen.html) macro use. - -/// Initialization Methods inner [`#[near]`](../attr.near.html) annotation. More details can be found [here](https://docs.near.org/sdk/rust/contract-structure/near-bindgen#initialization-methods) -/// -/// By default, the `Default::default()` implementation of a contract will be used to initialize a contract. There can be a custom initialization function which takes parameters or performs custom logic with the following `#[init]` annotation: -/// # Examples -/// -/// ## Basic example -/// -/// ```rust -/// use near_sdk::{log, near}; -/// -/// #[near(contract_state)] -/// #[derive(Default)] -/// pub struct Counter { -/// value: u64, -/// } -/// -/// #[near] -/// impl Counter { -/// #[init] -/// pub fn new(value: u64) -> Self { -/// log!("Custom counter initialization!"); -/// Self { value } -/// } -/// } -/// ``` -pub fn init() {} - -/// Payable Methods inner [`#[near]`](../attr.near.html) annotation. More details can be found [here](https://docs.near.org/sdk/rust/contract-structure/near-bindgen#payable-methods) -/// -/// Methods can be annotated with `#[payable]` to allow tokens to be transferred with the method invocation. For more information, see payable methods. -/// -/// To declare a function as payable, use the `#[payable]` annotation as follows: -/// # Examples -/// -/// ## Basic example -/// -/// ```rust -///use near_sdk::near; -/// -/// #[near(contract_state)] -/// #[derive(Default)] -/// pub struct Counter { -/// val: i8, -/// } -/// -/// #[near] -/// impl Counter { -/// #[payable] -/// pub fn my_method(&mut self) { -/// //... -/// } -/// } -/// ``` -pub fn payable() {} - -/// Private Methods inner [`#[near]`](../attr.near.html) annotation. More details can be found [here](https://docs.near.org/sdk/rust/contract-structure/near-bindgen#private-methods) -/// -/// Some methods need to be exposed to allow the contract to call a method on itself through a promise, but want to disallow any other contract to call it. For this, use the `#[private]` annotation to panic when this method is called externally. See [private methods](https://docs.near.org/sdk/rust/contract-interface/private-methods) for more information. -/// -/// This annotation can be applied to any method through the following: -/// # Examples -/// -/// ## Basic example -/// -/// ```rust -/// use near_sdk::near; -/// -/// #[near(contract_state)] -/// #[derive(Default)] -/// pub struct Counter { -/// val: u64, -/// } -/// -/// #[near] -/// impl Counter { -/// #[private] -/// pub fn my_method(&mut self) { -/// // ... -/// } -/// } -/// ``` -pub fn private() {} - -/// Result serialization inner [`#[near]`](../attr.near.html) annotation. -/// -/// Only one of `borsh` or `json` can be specified. -/// -/// # Examples -/// -/// ## Basic example -/// -/// ```rust -/// use near_sdk::near; -/// -/// #[near(contract_state)] -/// #[derive(Default)] -/// pub struct Counter { -/// val: u64, -/// } -/// -/// #[near] -/// impl Counter { -/// #[result_serializer(borsh)] -/// pub fn add_borsh(&self, #[serializer(borsh)] _a: Vec) { -/// // .. -/// } -/// } -/// ``` -pub fn result_serializer() {} - -/// Support Result types regardless of how they're referred to inner [`#[near]`](../attr.near.html) annotation. -/// -/// Have `#[handle_result]` to Support Result types regardless of how they're referred to -/// Function marked with `#[handle_result]` should return `Result (where E implements FunctionError)`. If you're trying to use a type alias for `Result`, try `#[handle_result(aliased)]` -/// -/// # Examples -/// -/// ## Basic example -/// -/// ```rust -/// use near_sdk::{near, AccountId, Promise, PromiseError}; -/// -/// #[near(contract_state)] -/// #[derive(Default)] -/// pub struct Counter { -/// val: u64, -/// } -/// -/// #[near] -/// impl Counter { -/// #[handle_result] -/// pub fn get_result( -/// &self, -/// account_id: AccountId, -/// #[callback_result] set_status_result: Result<(), PromiseError>, -/// ) -> Result<(), &'static str> { -/// // .. -/// Ok(()) -/// } -/// } -/// ``` -pub fn handle_result() {} diff --git a/near-sdk/src/near_annotations.rs b/near-sdk/src/near_annotations.rs new file mode 100644 index 000000000..65114e3dc --- /dev/null +++ b/near-sdk/src/near_annotations.rs @@ -0,0 +1,19 @@ +//! `#[near]` and `#[near_bindgen]` documentation module +//! +//! This is not a real module; here we document the attributes that [`#[near]`](crate::near) +//! and [`#[near_bindgen]`](crate::near_bindgen) macro use. + +/// See [`near_sdk::near #[init]`](macro@crate::near#init-sub-attribute) +pub fn init() {} + +/// See [`near_sdk::near #[payable]`](macro@crate::near#payable-sub-attribute) +pub fn payable() {} + +/// See [`near_sdk::near #[private]`](macro@crate::near#private-sub-attribute) +pub fn private() {} + +/// See [`near_sdk::near #[result_serializer]`](macro@crate::near#result_serializer-sub-attribute) +pub fn result_serializer() {} + +/// See [`near_sdk::near #[handle_result]`](macro@crate::near#handle_result-sub-attribute) +pub fn handle_result() {} From b3713aff3f7c026c18bfb0fd112ac817d0e198bf Mon Sep 17 00:00:00 2001 From: akorchyn Date: Tue, 4 Feb 2025 14:22:02 +0200 Subject: [PATCH 02/14] self-review --- near-sdk/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 682479657..6978444ef 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -358,7 +358,7 @@ extern crate quickcheck; /// ### Basic error handling example /// /// This example shows how to use error handling in a contract when the types are defined in the contract. -/// This way the contract can utilize result types and panic with the type using its `ToString` implementation +/// This way the contract can utilize result types and panic with the type using its [ToString] implementation /// /// ```rust /// use near_sdk::{near, FunctionError}; @@ -554,7 +554,7 @@ pub use near_sdk_macros::EventMetadata; pub use near_sdk_macros::NearSchema; /// `FunctionError` generates implementation for `near_sdk::FunctionError` trait. -/// It allows contract runtime to panic with the type using its `ToString` implementation +/// It allows contract runtime to panic with the type using its [ToString] implementation /// as the message. /// ## Example /// ```rust From 578e7a8a11b8e1206d15d42bb7c071319601388a Mon Sep 17 00:00:00 2001 From: akorchyn Date: Tue, 4 Feb 2025 14:49:45 +0200 Subject: [PATCH 03/14] added annotations to other entries --- near-sdk/src/lib.rs | 143 +++++++++++++++---------------- near-sdk/src/near_annotations.rs | 6 ++ 2 files changed, 77 insertions(+), 72 deletions(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 6978444ef..5b8269aab 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -142,78 +142,6 @@ extern crate quickcheck; /// } /// ``` /// -/// # Events Standard: -/// -/// By passing `event_json` as an argument `near_bindgen` will generate the relevant code to format events -/// according to [NEP-297](https://github.com/near/NEPs/blob/master/neps/nep-0297.md) -/// -/// For parameter serialization, this macro will generate a wrapper struct to include the NEP-297 standard fields `standard` and `version` -/// as well as include serialization reformatting to include the `event` and `data` fields automatically. -/// The `standard` and `version` values must be included in the enum and variant declaration (see example below). -/// By default this will be JSON deserialized with `serde` -/// -/// The version is required to allow backward compatibility. The older back-end will use the version field to determine if the event is supported. -/// -/// ## Examples -/// -/// ```rust -/// use near_sdk::{near, AccountId}; -/// -/// # #[near(contract_state)] -/// # pub struct Contract { -/// # data: i8, -/// # } -/// #[near(event_json(standard = "nepXXX"))] -/// pub enum MyEvents { -/// #[event_version("1.0.0")] -/// Swap { token_in: AccountId, token_out: AccountId, amount_in: u128, amount_out: u128 }, -/// -/// #[event_version("2.0.0")] -/// StringEvent(String), -/// -/// #[event_version("3.0.0")] -/// EmptyEvent -/// } -/// -/// #[near] -/// impl Contract { -/// pub fn some_function(&self) { -/// MyEvents::StringEvent( -/// String::from("some_string") -/// ).emit(); -/// } -/// -/// } -/// ``` -/// -/// # Contract Source Metadata Standard: -/// -/// By using `contract_metadata` as an argument `near` will populate the contract metadata -/// according to [`NEP-330`]() standard. This still applies even when `#[near]` is used without -/// any arguments. -/// -/// All fields(version, link) are optional and will be populated with defaults from the Cargo.toml file if not specified. -/// The `standard` will be populated with `nep330` by default. -/// -/// Any additional standards can be added and should be specified using the `standard` sub-attribute. -/// -/// The `contract_source_metadata()` view function will be added and can be used to retrieve the source metadata. -/// Also, the source metadata will be stored as a constant, `CONTRACT_SOURCE_METADATA`, in the contract code. -/// -/// ## Examples -/// -/// ```rust -/// use near_sdk::near; -/// -/// #[near(contract_metadata( -/// version = "39f2d2646f2f60e18ab53337501370dc02a5661c", -/// link = "https://github.com/near-examples/nft-tutorial", -/// standard(standard = "nep171", version = "1.0.0"), -/// standard(standard = "nep177", version = "2.0.0"), -/// ))] -/// struct Contract {} -/// ``` -/// /// # Sub-attributes /// /// ## init sub-attribute @@ -420,6 +348,77 @@ extern crate quickcheck; /// } /// } /// ``` +/// +/// ## event_json sub-attribute +/// +/// By passing `event_json` as an argument `near` will generate the relevant code to format events +/// according to [NEP-297](https://github.com/near/NEPs/blob/master/neps/nep-0297.md) +/// +/// For parameter serialization, this macro will generate a wrapper struct to include the NEP-297 standard fields `standard` and `version` +/// as well as include serialization reformatting to include the `event` and `data` fields automatically. +/// The `standard` and `version` values must be included in the enum and variant declaration (see example below). +/// By default this will be JSON deserialized with `serde` +/// +/// The version is required to allow backward compatibility. The older back-end will use the version field to determine if the event is supported. +/// +/// ### Basic example +/// +/// ```rust +/// use near_sdk::{near, AccountId}; +/// +/// # #[near(contract_state)] +/// # pub struct Contract { +/// # data: i8, +/// # } +/// #[near(event_json(standard = "nepXXX"))] +/// pub enum MyEvents { +/// #[event_version("1.0.0")] +/// Swap { token_in: AccountId, token_out: AccountId, amount_in: u128, amount_out: u128 }, +/// +/// #[event_version("2.0.0")] +/// StringEvent(String), +/// +/// #[event_version("3.0.0")] +/// EmptyEvent +/// } +/// +/// #[near] +/// impl Contract { +/// pub fn some_function(&self) { +/// MyEvents::StringEvent( +/// String::from("some_string") +/// ).emit(); +/// } +/// +/// } +/// ``` +/// +/// ## contract_metadata sub-attribute +/// By using `contract_metadata` as an argument `near` will populate the contract metadata +/// according to [`NEP-330`]() standard. This still applies even when `#[near]` is used without +/// any arguments. +/// +/// All fields(version, link) are optional and will be populated with defaults from the Cargo.toml file if not specified. +/// The `standard` will be populated with `nep330` by default. +/// +/// Any additional standards can be added and should be specified using the `standard` sub-attribute. +/// +/// The `contract_source_metadata()` view function will be added and can be used to retrieve the source metadata. +/// Also, the source metadata will be stored as a constant, `CONTRACT_SOURCE_METADATA`, in the contract code. +/// +/// ### Basic example +/// +/// ```rust +/// use near_sdk::near; +/// +/// #[near(contract_metadata( +/// version = "39f2d2646f2f60e18ab53337501370dc02a5661c", +/// link = "https://github.com/near-examples/nft-tutorial", +/// standard(standard = "nep171", version = "1.0.0"), +/// standard(standard = "nep177", version = "2.0.0"), +/// ))] +/// struct Contract {} +/// ``` pub use near_sdk_macros::near; /// This macro is deprecated. Use [near] instead. The difference between `#[near]` and `#[near_bindgen]` is that diff --git a/near-sdk/src/near_annotations.rs b/near-sdk/src/near_annotations.rs index 65114e3dc..bb50e091e 100644 --- a/near-sdk/src/near_annotations.rs +++ b/near-sdk/src/near_annotations.rs @@ -17,3 +17,9 @@ pub fn result_serializer() {} /// See [`near_sdk::near #[handle_result]`](macro@crate::near#handle_result-sub-attribute) pub fn handle_result() {} + +/// See [`near_sdk::near #[event_json]`](macro@crate::near#event_json-sub-attribute) +pub fn event_json() {} + +/// See [`near_sdk::near #[contract_metadata]`](macro@crate::near#contract_metadata-sub-attribute) +pub fn contract_metadata() {} From 7e03d10f677135fe4229ddf58e23a0d3fbe1bf57 Mon Sep 17 00:00:00 2001 From: akorchyn Date: Tue, 4 Feb 2025 15:53:37 +0200 Subject: [PATCH 04/14] updated readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 742ae8976..7bb392e38 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ **Release notes and unreleased changes can be found in the [CHANGELOG](https://github.com/near/near-sdk-rs/blob/master/CHANGELOG.md)** -## Example +## Example. For more information, see the [near](https://docs.rs/near-sdk/latest/near_sdk/attr.near.html) documentation Wrap a struct in `#[near]` and it generates a smart contract compatible with the NEAR blockchain: ```rust From 8df7c52026ea93aa5391503adcf198e78617611d Mon Sep 17 00:00:00 2001 From: akorchyn Date: Wed, 5 Feb 2025 17:40:34 +0200 Subject: [PATCH 05/14] review --- near-sdk/src/lib.rs | 107 ++++++++++++++++++++----------- near-sdk/src/near_annotations.rs | 24 +++++-- 2 files changed, 87 insertions(+), 44 deletions(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 5b8269aab..5dfda82e4 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -104,30 +104,16 @@ extern crate quickcheck; /// /// The macro is a syntactic sugar for [near_bindgen] and expands to the [near_bindgen] macro invocations. /// -/// ## Example +/// # Sub-attributes /// -/// ```rust -/// use near_sdk::near; +/// ## `#[near(contract_state)]` (annotates structs/enums) /// -/// #[near(serializers=[borsh, json])] -/// struct MyStruct { -/// pub name: String, -/// } -/// ``` +/// The macro sub-attribute prepares a struct/enum to be a contract state. /// /// This macro will generate code to load and deserialize state if the `self` parameter is included /// as well as saving it back to state if `&mut self` is used. /// -/// # Usage for enum / struct -/// -/// If the macro is used with struct or enum, it will make the struct or enum serializable with either -/// Borsh or Json depending on serializers passed. Use `#[near(serializers=[borsh])]` to make it serializable with Borsh. -/// Or use `#[near(serializers=[json])]` to make it serializable with Json. By default, borsh is used. -/// You can also specify both and none. BorshSchema or JsonSchema are always generated if respective serializer is toggled on. -/// -/// If you want the struct/enum to be a contract state, you can pass in the contract_state argument. -/// -/// ## Example +/// ### Basic example /// ```rust /// use near_sdk::near; /// @@ -142,13 +128,64 @@ extern crate quickcheck; /// } /// ``` /// -/// # Sub-attributes +/// ## `#[near(serializers=[...])` (annotates structs/enums) +/// +/// The macro sub-attribute makes the struct or enum serializable with either json or borsh. By default, borsh is used. /// -/// ## init sub-attribute +/// ### Make struct/enum serializable with borsh +/// +/// ```rust +/// use near_sdk::near; +/// +/// #[near(serializers=[borsh])] +/// pub enum MyEnum { +/// Variant1, +/// } +/// +/// #[near(serializers=[borsh])] +/// pub struct MyStruct { +/// pub name: String, +/// } +/// ``` +/// +/// ### Make struct/enum serializable with json +/// +/// ```rust +/// use near_sdk::near; +/// #[near(serializers=[json])] +/// pub enum MyEnum { +/// Variant1, +/// } +/// +/// #[near(serializers=[json])] +/// pub struct MyStruct { +/// pub name: String, +/// } +/// ``` +/// +/// ### Make struct/enum serializable with both borsh and json +/// +/// ```rust +/// use near_sdk::near; +/// #[near(serializers=[borsh, json])] +/// pub enum MyEnum { +/// Variant1, +/// } +/// +/// #[near(serializers=[borsh, json])] +/// pub struct MyStruct { +/// pub name: String, +/// } +/// ``` +/// +/// ## `#[init]` (annotates methods of a type in its `impl` block) /// /// Contract initialization method annotation. More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/storage#initializing-the-state) /// -/// By default, the `Default::default()` implementation of a contract will be used to initialize a contract. There can be a custom initialization function which takes parameters or performs custom logic with the following `#[init]` annotation: +/// By default, the `Default::default()` implementation of a contract will be used to initialize a contract. +/// There can be a custom initialization function which takes parameters or performs custom logic with the following `#[init]` annotation. +/// +/// You can provide several initialization functions. /// /// ### Basic example /// @@ -171,7 +208,7 @@ extern crate quickcheck; /// } /// ``` /// -/// ## payable sub-attribute +/// ## `#[payable]` (annotates methods of a type in its `impl` block) /// /// Specifies that the method can accept NEAR tokens. More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/functions#payable-functions) /// @@ -199,14 +236,12 @@ extern crate quickcheck; /// } /// ``` /// -/// ## private sub-attribute -/// -/// More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/functions#private-functions) +/// ## `#[private]` (annotates methods of a type in its `impl` block)] /// -/// Some methods need to be exposed to allow the contract to call a method on itself through a promise, but want to disallow any other contract to call it. -/// For this, use the `#[private]` annotation to panic when this method is called externally. See [private methods](https://docs.near.org/build/smart-contracts/anatomy/functions#private-functions) for more information. +/// The macro sub-attribute forbids to call the method except from within the contract. +/// This is useful for internal methods that should not be called from outside the contract. /// -/// This annotation can be applied to any method through the following: +/// More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/functions#private-functions) /// /// ### Basic example /// @@ -228,14 +263,11 @@ extern crate quickcheck; /// } /// ``` /// -/// ## result_serializer sub-attribute +/// ## `#[result_serializer(...)]` (annotates methods of a type in its `impl` block) /// -/// The macro defines the serializer for parameter and function return serialization. +/// The macro sub-attribute defines the serializer for function return serialization. /// Only one of `borsh` or `json` can be specified. /// -/// If the macro is used with Impl section, for parameter serialization, this macro will generate a struct with all of the parameters as -/// fields and derive deserialization for it. By default this will be JSON deserialized with `serde` -/// but can be overwritten by using `#[serializer(borsh)]`: /// ```rust /// use near_sdk::near; /// @@ -253,7 +285,7 @@ extern crate quickcheck; /// } /// ``` /// -/// `#[near]` will also handle serializing and setting the return value of the +/// `#[near]` will handle serializing and setting the return value of the /// function execution based on what type is returned by the function. By default, this will be /// done through `serde` serialized as JSON, but this can be overridden using /// `#[result_serializer(borsh)]`: @@ -277,7 +309,7 @@ extern crate quickcheck; /// } /// ``` /// -/// ## handle_result sub-attribute +/// ## `#[handle_result]` (annotates methods of a type in its `impl` block) /// /// Have `#[handle_result]` to Support Result types regardless of how they're referred to /// Function marked with `#[handle_result]` should return `Result` (where E implements [FunctionError]). @@ -349,7 +381,7 @@ extern crate quickcheck; /// } /// ``` /// -/// ## event_json sub-attribute +/// ## `#[event_json(...)]` (annotates enums) /// /// By passing `event_json` as an argument `near` will generate the relevant code to format events /// according to [NEP-297](https://github.com/near/NEPs/blob/master/neps/nep-0297.md) @@ -393,7 +425,8 @@ extern crate quickcheck; /// } /// ``` /// -/// ## contract_metadata sub-attribute +/// ## `#[near(contract_metadata(...))]` (annotates structs/enums) +/// /// By using `contract_metadata` as an argument `near` will populate the contract metadata /// according to [`NEP-330`]() standard. This still applies even when `#[near]` is used without /// any arguments. diff --git a/near-sdk/src/near_annotations.rs b/near-sdk/src/near_annotations.rs index bb50e091e..981d0420f 100644 --- a/near-sdk/src/near_annotations.rs +++ b/near-sdk/src/near_annotations.rs @@ -3,23 +3,33 @@ //! This is not a real module; here we document the attributes that [`#[near]`](crate::near) //! and [`#[near_bindgen]`](crate::near_bindgen) macro use. -/// See [`near_sdk::near #[init]`](macro@crate::near#init-sub-attribute) +/// See [`near_sdk::near #[init]`](crate::near#init-annotates-methods-of-a-type-in-its-impl-block) pub fn init() {} -/// See [`near_sdk::near #[payable]`](macro@crate::near#payable-sub-attribute) +/// See [`near_sdk::near #[payable]`](crate::near#payable-annotates-methods-of-a-type-in-its-impl-block) pub fn payable() {} -/// See [`near_sdk::near #[private]`](macro@crate::near#private-sub-attribute) +/// See [`near_sdk::near #[private]`](crate::near#private-annotates-methods-of-a-type-in-its-impl-block) pub fn private() {} -/// See [`near_sdk::near #[result_serializer]`](macro@crate::near#result_serializer-sub-attribute) +/// See [`near_sdk::near #[result_serializer]`](crate::near#result_serializer-annotates-methods-of-a-type-in-its-impl-block) pub fn result_serializer() {} -/// See [`near_sdk::near #[handle_result]`](macro@crate::near#handle_result-sub-attribute) +/// See [`near_sdk::near #[handle_result]`](crate::near#handle_result-annotates-methods-of-a-type-in-its-impl-block) pub fn handle_result() {} -/// See [`near_sdk::near #[event_json]`](macro@crate::near#event_json-sub-attribute) +/// See [`near_sdk::near #[event_json(...)]`](crate::near#event_json-annotates-enums) pub fn event_json() {} -/// See [`near_sdk::near #[contract_metadata]`](macro@crate::near#contract_metadata-sub-attribute) +/// See [`near_sdk::near #[near(contract_metadata(...))]`](crate::near#nearcontract_metadata-annotates-structsenums) pub fn contract_metadata() {} + +/// See [`near_sdk::near #[near(serializers=[...])]`](crate::near#nearserializers-annotates-structsenums) +/// +/// Macro specific to the [`#[near]`](crate::near) only. +pub fn serializers() {} + +/// See [`near_sdk::near #[near(contract_state)]`](crate::near#nearcontract_state-annotates-structsenums) +/// +/// Macro specific to the [`#[near]`](crate::near) only. +pub fn contract_state() {} From af96137cd2ce40ec9b81b865eaad42c789a5fff7 Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 12:59:16 +0200 Subject: [PATCH 06/14] review --- near-sdk/src/lib.rs | 92 ++++++++++++++++++-------------- near-sdk/src/near_annotations.rs | 24 ++++++--- 2 files changed, 71 insertions(+), 45 deletions(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 5dfda82e4..5ae57a01e 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -103,12 +103,14 @@ extern crate quickcheck; /// as generating the glue code to be a valid NEAR contract. /// /// The macro is a syntactic sugar for [near_bindgen] and expands to the [near_bindgen] macro invocations. +/// Both of them share the same sub-attributes, except for those that are explicitly marked as specific to the [near] macro. /// /// # Sub-attributes /// /// ## `#[near(contract_state)]` (annotates structs/enums) /// /// The macro sub-attribute prepares a struct/enum to be a contract state. +/// **The sub-attribute specific to the [near] macro only.** /// /// This macro will generate code to load and deserialize state if the `self` parameter is included /// as well as saving it back to state if `&mut self` is used. @@ -131,6 +133,7 @@ extern crate quickcheck; /// ## `#[near(serializers=[...])` (annotates structs/enums) /// /// The macro sub-attribute makes the struct or enum serializable with either json or borsh. By default, borsh is used. +/// **The sub-attribute specific to the [near] macro only.** /// /// ### Make struct/enum serializable with borsh /// @@ -178,6 +181,23 @@ extern crate quickcheck; /// } /// ``` /// +/// ## `#[serializer(...)]` (annotates function arguments) +/// +/// The macro sub-attribute makes the function argument serializable with either json or borsh. By default, borsh is used. +/// +/// ### Basic example +/// +/// ```rust +/// use near_sdk::near; +///# #[near(contract_state)] +///# pub struct Contract {} +/// +/// #[near] +/// impl Contract { +/// pub fn some_function(&self, #[serializer(borsh)] a: String, #[serializer] b: String) {} +/// } +/// ``` +/// /// ## `#[init]` (annotates methods of a type in its `impl` block) /// /// Contract initialization method annotation. More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/storage#initializing-the-state) @@ -279,7 +299,7 @@ extern crate quickcheck; /// #[near] /// impl MyContract { /// #[result_serializer(borsh)] -/// pub fn borsh_parameters(&self, #[serializer(borsh)] a: String, #[serializer(borsh)] b: String) -> String { +/// pub fn borsh_parameters(&self) -> String { /// format!("{} {}", a, b) /// } /// } @@ -315,9 +335,31 @@ extern crate quickcheck; /// Function marked with `#[handle_result]` should return `Result` (where E implements [FunctionError]). /// If you're trying to use a type alias for `Result`, try `#[handle_result(aliased)]` /// -/// ### Basic error handling example +/// ### Basic error handling with Result +/// +/// ```rust +/// use near_sdk::{near, AccountId, Promise, PromiseError}; +/// +/// #[near(contract_state)] +/// #[derive(Default)] +/// pub struct Counter { +/// val: u64, +/// } +/// +/// #[near] +/// impl Counter { +/// #[handle_result] +/// pub fn some_function2( +/// &self, +/// ) -> Result<(), &'static str> { +/// Err("error") +/// } +/// } +/// ``` +/// +/// ### Typed error handling /// -/// This example shows how to use error handling in a contract when the types are defined in the contract. +/// This example shows how to use error handling in a contract when the error are defined in the contract. /// This way the contract can utilize result types and panic with the type using its [ToString] implementation /// /// ```rust @@ -335,17 +377,17 @@ extern crate quickcheck; /// } /// } /// } -/// -/// #[near(contract_state)] -/// pub struct MyContract { -/// pub some_value: u64, -/// } +///# #[near(contract_state)] +///# #[derive(Default)] +///# pub struct Counter { +///# val: u64, +///# } /// /// #[near] -/// impl MyContract { +/// impl Counter { /// #[handle_result] /// pub fn some_function(&self) -> Result<(), MyError> { -/// if self.some_value == 0 { +/// if self.val == 0 { /// return Err(MyError::SomePanicError); /// } /// Ok(()) @@ -353,35 +395,7 @@ extern crate quickcheck; /// } /// ``` /// -/// ### Basic callback function example -/// -/// This examples shows how to create a function that handles the result of a -/// cross-chain call. For more details, see [here](https://docs.near.org/build/smart-contracts/anatomy/crosscontract#callback-function) -/// -/// ```rust -/// use near_sdk::{near, AccountId, Promise, PromiseError}; -/// -/// #[near(contract_state)] -/// #[derive(Default)] -/// pub struct Counter { -/// val: u64, -/// } -/// -/// #[near] -/// impl Counter { -/// #[handle_result] -/// pub fn get_result( -/// &self, -/// account_id: AccountId, -/// #[callback_result] set_status_result: Result<(), PromiseError>, -/// ) -> Result<(), &'static str> { -/// // .. -/// Ok(()) -/// } -/// } -/// ``` -/// -/// ## `#[event_json(...)]` (annotates enums) +/// ## `#[near(event_json(...))]` (annotates enums) /// /// By passing `event_json` as an argument `near` will generate the relevant code to format events /// according to [NEP-297](https://github.com/near/NEPs/blob/master/neps/nep-0297.md) diff --git a/near-sdk/src/near_annotations.rs b/near-sdk/src/near_annotations.rs index 981d0420f..1dad6fbe8 100644 --- a/near-sdk/src/near_annotations.rs +++ b/near-sdk/src/near_annotations.rs @@ -2,8 +2,21 @@ //! //! This is not a real module; here we document the attributes that [`#[near]`](crate::near) //! and [`#[near_bindgen]`](crate::near_bindgen) macro use. +//! +//! `near_bindgen` and `near_sdk` shares almost the same attributes: +//! * init +//! * payable +//! * private +//! * handle_result +//! * event_json +//! * contract_metadata +//! * serializer +//! +//! These attributes are only part of the `near` macro. +//! * serializers +//! * contract_state -/// See [`near_sdk::near #[init]`](crate::near#init-annotates-methods-of-a-type-in-its-impl-block) +/// See [`near_sdk::near #[init]`](crate::near#init-annotates-methods-of-a-type-in-its-impl-block) for details. pub fn init() {} /// See [`near_sdk::near #[payable]`](crate::near#payable-annotates-methods-of-a-type-in-its-impl-block) @@ -18,18 +31,17 @@ pub fn result_serializer() {} /// See [`near_sdk::near #[handle_result]`](crate::near#handle_result-annotates-methods-of-a-type-in-its-impl-block) pub fn handle_result() {} -/// See [`near_sdk::near #[event_json(...)]`](crate::near#event_json-annotates-enums) +/// See [`near_sdk::near #[near(event_json(...))]`](crate::near#nearevent_json-annotates-enums) pub fn event_json() {} /// See [`near_sdk::near #[near(contract_metadata(...))]`](crate::near#nearcontract_metadata-annotates-structsenums) pub fn contract_metadata() {} +/// See [`near_sdk::near #[serializer(...)]`](crate::near#serializer-annotates-function-arguments) +pub fn serializer() {} + /// See [`near_sdk::near #[near(serializers=[...])]`](crate::near#nearserializers-annotates-structsenums) -/// -/// Macro specific to the [`#[near]`](crate::near) only. pub fn serializers() {} /// See [`near_sdk::near #[near(contract_state)]`](crate::near#nearcontract_state-annotates-structsenums) -/// -/// Macro specific to the [`#[near]`](crate::near) only. pub fn contract_state() {} From 89658e16a0918fa3c94389d59fad03cd5072969f Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 13:12:34 +0200 Subject: [PATCH 07/14] review --- near-sdk/src/lib.rs | 26 +++++++++++++------------- near-sdk/src/near_annotations.rs | 2 +- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 5ae57a01e..586255929 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -103,16 +103,16 @@ extern crate quickcheck; /// as generating the glue code to be a valid NEAR contract. /// /// The macro is a syntactic sugar for [near_bindgen] and expands to the [near_bindgen] macro invocations. -/// Both of them share the same sub-attributes, except for those that are explicitly marked as specific to the [near] macro. +/// Both of them share the same attributes, except for those that are explicitly marked as specific to the [near] macro. ([1](near#nearserializers-annotates-structsenums), [2](near#nearcontract_state-annotates-structsenums)) /// -/// # Sub-attributes +/// # Attributes /// /// ## `#[near(contract_state)]` (annotates structs/enums) /// -/// The macro sub-attribute prepares a struct/enum to be a contract state. -/// **The sub-attribute specific to the [near] macro only.** +/// The attribute prepares a struct/enum to be a contract state. +/// **The attribute specific to the [near] macro only.** /// -/// This macro will generate code to load and deserialize state if the `self` parameter is included +/// This attribute will generate code to load and deserialize state if the `self` parameter is included /// as well as saving it back to state if `&mut self` is used. /// /// ### Basic example @@ -132,8 +132,8 @@ extern crate quickcheck; /// /// ## `#[near(serializers=[...])` (annotates structs/enums) /// -/// The macro sub-attribute makes the struct or enum serializable with either json or borsh. By default, borsh is used. -/// **The sub-attribute specific to the [near] macro only.** +/// The attribute makes the struct or enum serializable with either json or borsh. By default, borsh is used. +/// **The attribute specific to the [near] macro only.** /// /// ### Make struct/enum serializable with borsh /// @@ -183,7 +183,7 @@ extern crate quickcheck; /// /// ## `#[serializer(...)]` (annotates function arguments) /// -/// The macro sub-attribute makes the function argument serializable with either json or borsh. By default, borsh is used. +/// The attribute makes the function argument serializable with either json or borsh. By default, json is used. /// /// ### Basic example /// @@ -194,7 +194,7 @@ extern crate quickcheck; /// /// #[near] /// impl Contract { -/// pub fn some_function(&self, #[serializer(borsh)] a: String, #[serializer] b: String) {} +/// pub fn some_function(&self, #[serializer(json)] a: String, #[serializer] b: String) {} /// } /// ``` /// @@ -258,7 +258,7 @@ extern crate quickcheck; /// /// ## `#[private]` (annotates methods of a type in its `impl` block)] /// -/// The macro sub-attribute forbids to call the method except from within the contract. +/// The attribute forbids to call the method except from within the contract. /// This is useful for internal methods that should not be called from outside the contract. /// /// More details can be found [here](https://docs.near.org/build/smart-contracts/anatomy/functions#private-functions) @@ -285,7 +285,7 @@ extern crate quickcheck; /// /// ## `#[result_serializer(...)]` (annotates methods of a type in its `impl` block) /// -/// The macro sub-attribute defines the serializer for function return serialization. +/// The attribute defines the serializer for function return serialization. /// Only one of `borsh` or `json` can be specified. /// /// ```rust @@ -300,7 +300,7 @@ extern crate quickcheck; /// impl MyContract { /// #[result_serializer(borsh)] /// pub fn borsh_parameters(&self) -> String { -/// format!("{} {}", a, b) +/// "hello_world".to_string() /// } /// } /// ``` @@ -448,7 +448,7 @@ extern crate quickcheck; /// All fields(version, link) are optional and will be populated with defaults from the Cargo.toml file if not specified. /// The `standard` will be populated with `nep330` by default. /// -/// Any additional standards can be added and should be specified using the `standard` sub-attribute. +/// Any additional standards can be added and should be specified using the `standard` attribute. /// /// The `contract_source_metadata()` view function will be added and can be used to retrieve the source metadata. /// Also, the source metadata will be stored as a constant, `CONTRACT_SOURCE_METADATA`, in the contract code. diff --git a/near-sdk/src/near_annotations.rs b/near-sdk/src/near_annotations.rs index 1dad6fbe8..1dca4a56c 100644 --- a/near-sdk/src/near_annotations.rs +++ b/near-sdk/src/near_annotations.rs @@ -16,7 +16,7 @@ //! * serializers //! * contract_state -/// See [`near_sdk::near #[init]`](crate::near#init-annotates-methods-of-a-type-in-its-impl-block) for details. +/// See [`near_sdk::near #[init]`](crate::near#init-annotates-methods-of-a-type-in-its-impl-block) pub fn init() {} /// See [`near_sdk::near #[payable]`](crate::near#payable-annotates-methods-of-a-type-in-its-impl-block) From 231a45b3b1a13aa9c2fe5cdca0d6502c2bb2ef6b Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 13:14:59 +0200 Subject: [PATCH 08/14] note --- near-sdk/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 586255929..7738e023f 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -184,6 +184,7 @@ extern crate quickcheck; /// ## `#[serializer(...)]` (annotates function arguments) /// /// The attribute makes the function argument serializable with either json or borsh. By default, json is used. +/// Please, note that all the arguments of the function should be using the same serializer. /// /// ### Basic example /// @@ -194,7 +195,7 @@ extern crate quickcheck; /// /// #[near] /// impl Contract { -/// pub fn some_function(&self, #[serializer(json)] a: String, #[serializer] b: String) {} +/// pub fn some_function(&self, #[serializer(borsh)] a: String, #[serializer(borsh)] b: String) {} /// } /// ``` /// From 695c873c5c8ba6d0c69f0dc8772825dc671edaa1 Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 14:20:49 +0200 Subject: [PATCH 09/14] review --- near-sdk/src/lib.rs | 36 ++---------------------------------- 1 file changed, 2 insertions(+), 34 deletions(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 7738e023f..095cdacad 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -112,9 +112,6 @@ extern crate quickcheck; /// The attribute prepares a struct/enum to be a contract state. /// **The attribute specific to the [near] macro only.** /// -/// This attribute will generate code to load and deserialize state if the `self` parameter is included -/// as well as saving it back to state if `&mut self` is used. -/// /// ### Basic example /// ```rust /// use near_sdk::near; @@ -123,11 +120,6 @@ extern crate quickcheck; /// pub struct Contract { /// data: i8, /// } -/// -/// #[near] -/// impl Contract { -/// pub fn some_function(&self) {} -/// } /// ``` /// /// ## `#[near(serializers=[...])` (annotates structs/enums) @@ -195,7 +187,7 @@ extern crate quickcheck; /// /// #[near] /// impl Contract { -/// pub fn some_function(&self, #[serializer(borsh)] a: String, #[serializer(borsh)] b: String) {} +/// pub fn borsh_arguments(&self, #[serializer(borsh)] a: String, #[serializer(borsh)] b: String) {} /// } /// ``` /// @@ -300,36 +292,12 @@ extern crate quickcheck; /// #[near] /// impl MyContract { /// #[result_serializer(borsh)] -/// pub fn borsh_parameters(&self) -> String { +/// pub fn borsh_return_value(&self) -> String { /// "hello_world".to_string() /// } /// } /// ``` /// -/// `#[near]` will handle serializing and setting the return value of the -/// function execution based on what type is returned by the function. By default, this will be -/// done through `serde` serialized as JSON, but this can be overridden using -/// `#[result_serializer(borsh)]`: -/// -/// ### Basic example -/// -/// ```rust -/// use near_sdk::near; -/// -/// # #[near(contract_state)] -/// # struct MyContract { -/// # pub name: String, -/// # } -/// -/// #[near] -/// impl MyContract { -/// #[result_serializer(borsh)] -/// pub fn borsh_parameters(&self) -> String { -/// self.name.clone() -/// } -/// } -/// ``` -/// /// ## `#[handle_result]` (annotates methods of a type in its `impl` block) /// /// Have `#[handle_result]` to Support Result types regardless of how they're referred to From 8f6ee2736c6b7227f9a752ed8f553bfc40c12280 Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 14:38:45 +0200 Subject: [PATCH 10/14] review --- near-sdk/src/lib.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 095cdacad..30dc4e295 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -109,7 +109,7 @@ extern crate quickcheck; /// /// ## `#[near(contract_state)]` (annotates structs/enums) /// -/// The attribute prepares a struct/enum to be a contract state. +/// This is a marker attribute to mark the `Contract` (which is usually one per crate). This attribute is also required to make the [`#[near(contract_metadata(...))]`](near#nearcontract_metadata-annotates-structsenums) attribute work. /// **The attribute specific to the [near] macro only.** /// /// ### Basic example @@ -422,11 +422,14 @@ extern crate quickcheck; /// The `contract_source_metadata()` view function will be added and can be used to retrieve the source metadata. /// Also, the source metadata will be stored as a constant, `CONTRACT_SOURCE_METADATA`, in the contract code. /// +/// **Please note that the `contract_metadata` will be ignored if `#[near(contract_state)]` is not used**. +/// /// ### Basic example /// /// ```rust /// use near_sdk::near; /// +/// #[near(contract_state)] /// #[near(contract_metadata( /// version = "39f2d2646f2f60e18ab53337501370dc02a5661c", /// link = "https://github.com/near-examples/nft-tutorial", From 30bd90c1591d9bb316a963f622bb5fbe98f2266c Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 14:40:27 +0200 Subject: [PATCH 11/14] added url --- near-sdk/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 30dc4e295..27a23c187 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -422,7 +422,7 @@ extern crate quickcheck; /// The `contract_source_metadata()` view function will be added and can be used to retrieve the source metadata. /// Also, the source metadata will be stored as a constant, `CONTRACT_SOURCE_METADATA`, in the contract code. /// -/// **Please note that the `contract_metadata` will be ignored if `#[near(contract_state)]` is not used**. +/// **Please note that the `contract_metadata` will be ignored if [`#[near(contract_state)]`](near#nearcontract_state-annotates-structsenums) is not used**. /// /// ### Basic example /// From 49424eab3cbabd4c31b9854f9b6866a3c0352126 Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 15:37:24 +0200 Subject: [PATCH 12/14] note that contract is only one per crate, and fixed doc comp --- near-sdk/src/lib.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 27a23c187..d2f332a33 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -109,7 +109,7 @@ extern crate quickcheck; /// /// ## `#[near(contract_state)]` (annotates structs/enums) /// -/// This is a marker attribute to mark the `Contract` (which is usually one per crate). This attribute is also required to make the [`#[near(contract_metadata(...))]`](near#nearcontract_metadata-annotates-structsenums) attribute work. +/// This is a marker attribute to mark the `Contract` (only one per crate is possible). This attribute is also required to make the [`#[near(contract_metadata(...))]`](near#nearcontract_metadata-annotates-structsenums) attribute work. /// **The attribute specific to the [near] macro only.** /// /// ### Basic example @@ -429,8 +429,7 @@ extern crate quickcheck; /// ```rust /// use near_sdk::near; /// -/// #[near(contract_state)] -/// #[near(contract_metadata( +/// #[near(contract_state, contract_metadata( /// version = "39f2d2646f2f60e18ab53337501370dc02a5661c", /// link = "https://github.com/near-examples/nft-tutorial", /// standard(standard = "nep171", version = "1.0.0"), From 4072acc2c9815ee0b6f7a710b61094f184b7df21 Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 15:47:12 +0200 Subject: [PATCH 13/14] reverted message --- near-sdk/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index d2f332a33..d438d0e4a 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -109,7 +109,7 @@ extern crate quickcheck; /// /// ## `#[near(contract_state)]` (annotates structs/enums) /// -/// This is a marker attribute to mark the `Contract` (only one per crate is possible). This attribute is also required to make the [`#[near(contract_metadata(...))]`](near#nearcontract_metadata-annotates-structsenums) attribute work. +/// The attribute prepares a struct/enum to be a contract state. This attribute is also required to make the [`#[near(contract_metadata(...))]`](near#nearcontract_metadata-annotates-structsenums) attribute work. /// **The attribute specific to the [near] macro only.** /// /// ### Basic example From 820d572f162d8e3b8125f2d4f22e1fc1096c2893 Mon Sep 17 00:00:00 2001 From: akorchyn Date: Thu, 6 Feb 2025 15:48:25 +0200 Subject: [PATCH 14/14] added message about one contract_state per crate --- near-sdk/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index d438d0e4a..39dab8644 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -109,7 +109,8 @@ extern crate quickcheck; /// /// ## `#[near(contract_state)]` (annotates structs/enums) /// -/// The attribute prepares a struct/enum to be a contract state. This attribute is also required to make the [`#[near(contract_metadata(...))]`](near#nearcontract_metadata-annotates-structsenums) attribute work. +/// The attribute prepares a struct/enum to be a contract state. Only one contract state is allowed per crate. +/// This attribute is also required to make the [`#[near(contract_metadata(...))]`](near#nearcontract_metadata-annotates-structsenums) attribute work. /// **The attribute specific to the [near] macro only.** /// /// ### Basic example