From 1b54fb2bc3bdc3e792ede4931c8a601d017ce2ec Mon Sep 17 00:00:00 2001 From: Spring Chiu Date: Thu, 30 May 2024 00:51:48 +0800 Subject: [PATCH 1/5] feat-issue-1177: add attribute string for indexing attribute string in near-sdk --- Cargo.toml | 1 + near-attribute-str/Cargo.toml | 8 ++ near-attribute-str/src/lib.rs | 76 +++++++++++++++++++ near-sdk-macros/Cargo.toml | 1 + .../core_impl/info_extractor/attr_sig_info.rs | 24 +++--- near-sdk/Cargo.toml | 1 + near-sdk/src/lib.rs | 1 + 7 files changed, 103 insertions(+), 9 deletions(-) create mode 100644 near-attribute-str/Cargo.toml create mode 100644 near-attribute-str/src/lib.rs diff --git a/Cargo.toml b/Cargo.toml index 0ac56340c..af1f3b28b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,6 +5,7 @@ members = [ "near-sdk-macros", "near-contract-standards", "near-sys", + "near-attribute-str", ] exclude = ["examples/"] diff --git a/near-attribute-str/Cargo.toml b/near-attribute-str/Cargo.toml new file mode 100644 index 000000000..37e8f11fb --- /dev/null +++ b/near-attribute-str/Cargo.toml @@ -0,0 +1,8 @@ +[package] +name = "near-attribute-str" +edition = "2021" +version.workspace = true + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] diff --git a/near-attribute-str/src/lib.rs b/near-attribute-str/src/lib.rs new file mode 100644 index 000000000..811a2ba2d --- /dev/null +++ b/near-attribute-str/src/lib.rs @@ -0,0 +1,76 @@ +/// 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 +///#[near] +///impl Counter { +/// #[init] +/// pub fn new(value: u64) -> Self { +/// log!("Custom counter initialization!"); +/// Self { value } +/// } +///} +/// ``` +#[allow(non_upper_case_globals)] +pub const init: &str = "init"; + +/// 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 +///#[payable] +///pub fn my_method(&mut self) { +/// ... +///} +/// ``` +#[allow(non_upper_case_globals)] +pub const payable: &str = "payable"; + +/// 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 +/// #[private] +/// pub fn my_method(&mut self) { +/// ... +///} +/// ``` +#[allow(non_upper_case_globals)] +pub const private: &str = "private"; + +/// Result serialization. +/// +/// Only one of `borsh` or `json` can be specified. +/// +/// # Examples +/// +/// ## Basic example +/// +/// ```rust +///#[result_serializer(borsh)] +///pub fn add_borsh(&self, #[serializer(borsh)] a: Pair, #[serializer(borsh)] b: Pair) -> Pair { +/// sum_pair(&a, &b) +///} +/// ``` +#[allow(non_upper_case_globals)] +pub const result_serializer: &str = "result_serializer"; + +/// Handle result +#[allow(non_upper_case_globals)] +pub const handle_result: &str = "handle_result"; diff --git a/near-sdk-macros/Cargo.toml b/near-sdk-macros/Cargo.toml index f09bcec78..d097d7862 100644 --- a/near-sdk-macros/Cargo.toml +++ b/near-sdk-macros/Cargo.toml @@ -24,6 +24,7 @@ Inflector = { version = "0.11.4", default-features = false, features = [] } darling = { version = "0.20.3", default-features = false } serde = { version = "1", default-features = false, features = ["serde_derive"] } serde_json = "1" +near-attribute-str = { path = "../near-attribute-str" } [dev-dependencies] insta = { version = "1.31.0", features = ["yaml"] } diff --git a/near-sdk-macros/src/core_impl/info_extractor/attr_sig_info.rs b/near-sdk-macros/src/core_impl/info_extractor/attr_sig_info.rs index 772565295..15292dc75 100644 --- a/near-sdk-macros/src/core_impl/info_extractor/attr_sig_info.rs +++ b/near-sdk-macros/src/core_impl/info_extractor/attr_sig_info.rs @@ -3,6 +3,7 @@ use super::{ ArgInfo, BindgenArgType, HandleResultAttr, InitAttr, MethodKind, SerializerAttr, SerializerType, }; use crate::core_impl::{utils, Returns}; +use near_attribute_str::{handle_result, init, payable, private, result_serializer}; use proc_macro2::{Span, TokenStream as TokenStream2}; use quote::ToTokens; use syn::spanned::Spanned; @@ -102,20 +103,24 @@ impl AttrSigInfo { for attr in original_attrs.iter() { let attr_str = attr.path().to_token_stream().to_string(); match attr_str.as_str() { - "init" => { + #[allow(non_upper_case_globals)] + init => { let mut init_attr = InitAttr { ignore_state: false }; if let Some(state) = args.ignore_state { init_attr.ignore_state = state; } visitor.visit_init_attr(attr, &init_attr)?; } - "payable" => { + #[allow(non_upper_case_globals)] + payable => { visitor.visit_payable_attr(attr)?; } - "private" => { + #[allow(non_upper_case_globals)] + private => { visitor.visit_private_attr(attr)?; } - "result_serializer" => { + #[allow(non_upper_case_globals)] + result_serializer => { if args.borsh.is_some() && args.json.is_some() { return Err(Error::new( attr.span(), @@ -135,13 +140,14 @@ impl AttrSigInfo { } visitor.visit_result_serializer_attr(attr, &serializer)?; } - "handle_result" => { + #[allow(non_upper_case_globals)] + handle_result => { if let Some(value) = args.aliased { - let handle_result = HandleResultAttr { check: value }; - visitor.visit_handle_result_attr(&handle_result); + let handle_result_attr = HandleResultAttr { check: value }; + visitor.visit_handle_result_attr(&handle_result_attr); } else { - let handle_result = HandleResultAttr { check: false }; - visitor.visit_handle_result_attr(&handle_result); + let handle_result_attr = HandleResultAttr { check: false }; + visitor.visit_handle_result_attr(&handle_result_attr); } } _ => { diff --git a/near-sdk/Cargo.toml b/near-sdk/Cargo.toml index 7488fe7bd..1f854f87e 100644 --- a/near-sdk/Cargo.toml +++ b/near-sdk/Cargo.toml @@ -33,6 +33,7 @@ once_cell = { version = "1.17", default-features = false } near-account-id = { version="1.0.0", features = ["serde", "borsh"] } near-gas = { version = "0.2.3", features = ["serde", "borsh"] } near-token = { version = "0.2.0", features = ["serde", "borsh"] } +near-attribute-str = { path = "../near-attribute-str" } [target.'cfg(target_arch = "wasm32")'.dependencies] wee_alloc = { version = "0.4.5", default-features = false, optional = true } diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 45df0dbcd..3b81939b6 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -63,6 +63,7 @@ static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT; pub use base64; pub use borsh; pub use bs58; +pub use near_attribute_str::*; #[cfg(feature = "abi")] pub use schemars; pub use serde; From 3d9b6eed34d7b4380fde8c9bcded0454be9e97b0 Mon Sep 17 00:00:00 2001 From: Spring Chiu Date: Fri, 31 May 2024 00:50:54 +0800 Subject: [PATCH 2/5] feat-issue-1177: use function to replace const str --- Cargo.toml | 1 - near-attribute-str/Cargo.toml | 8 - near-attribute-str/src/lib.rs | 76 ---------- near-sdk-macros/Cargo.toml | 1 - .../core_impl/info_extractor/attr_sig_info.rs | 24 ++- near-sdk/Cargo.toml | 1 - near-sdk/src/lib.rs | 3 +- near-sdk/src/near.rs | 142 ++++++++++++++++++ 8 files changed, 153 insertions(+), 103 deletions(-) delete mode 100644 near-attribute-str/Cargo.toml delete mode 100644 near-attribute-str/src/lib.rs create mode 100644 near-sdk/src/near.rs diff --git a/Cargo.toml b/Cargo.toml index af1f3b28b..0ac56340c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -5,7 +5,6 @@ members = [ "near-sdk-macros", "near-contract-standards", "near-sys", - "near-attribute-str", ] exclude = ["examples/"] diff --git a/near-attribute-str/Cargo.toml b/near-attribute-str/Cargo.toml deleted file mode 100644 index 37e8f11fb..000000000 --- a/near-attribute-str/Cargo.toml +++ /dev/null @@ -1,8 +0,0 @@ -[package] -name = "near-attribute-str" -edition = "2021" -version.workspace = true - -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html - -[dependencies] diff --git a/near-attribute-str/src/lib.rs b/near-attribute-str/src/lib.rs deleted file mode 100644 index 811a2ba2d..000000000 --- a/near-attribute-str/src/lib.rs +++ /dev/null @@ -1,76 +0,0 @@ -/// 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 -///#[near] -///impl Counter { -/// #[init] -/// pub fn new(value: u64) -> Self { -/// log!("Custom counter initialization!"); -/// Self { value } -/// } -///} -/// ``` -#[allow(non_upper_case_globals)] -pub const init: &str = "init"; - -/// 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 -///#[payable] -///pub fn my_method(&mut self) { -/// ... -///} -/// ``` -#[allow(non_upper_case_globals)] -pub const payable: &str = "payable"; - -/// 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 -/// #[private] -/// pub fn my_method(&mut self) { -/// ... -///} -/// ``` -#[allow(non_upper_case_globals)] -pub const private: &str = "private"; - -/// Result serialization. -/// -/// Only one of `borsh` or `json` can be specified. -/// -/// # Examples -/// -/// ## Basic example -/// -/// ```rust -///#[result_serializer(borsh)] -///pub fn add_borsh(&self, #[serializer(borsh)] a: Pair, #[serializer(borsh)] b: Pair) -> Pair { -/// sum_pair(&a, &b) -///} -/// ``` -#[allow(non_upper_case_globals)] -pub const result_serializer: &str = "result_serializer"; - -/// Handle result -#[allow(non_upper_case_globals)] -pub const handle_result: &str = "handle_result"; diff --git a/near-sdk-macros/Cargo.toml b/near-sdk-macros/Cargo.toml index d097d7862..f09bcec78 100644 --- a/near-sdk-macros/Cargo.toml +++ b/near-sdk-macros/Cargo.toml @@ -24,7 +24,6 @@ Inflector = { version = "0.11.4", default-features = false, features = [] } darling = { version = "0.20.3", default-features = false } serde = { version = "1", default-features = false, features = ["serde_derive"] } serde_json = "1" -near-attribute-str = { path = "../near-attribute-str" } [dev-dependencies] insta = { version = "1.31.0", features = ["yaml"] } diff --git a/near-sdk-macros/src/core_impl/info_extractor/attr_sig_info.rs b/near-sdk-macros/src/core_impl/info_extractor/attr_sig_info.rs index 15292dc75..772565295 100644 --- a/near-sdk-macros/src/core_impl/info_extractor/attr_sig_info.rs +++ b/near-sdk-macros/src/core_impl/info_extractor/attr_sig_info.rs @@ -3,7 +3,6 @@ use super::{ ArgInfo, BindgenArgType, HandleResultAttr, InitAttr, MethodKind, SerializerAttr, SerializerType, }; use crate::core_impl::{utils, Returns}; -use near_attribute_str::{handle_result, init, payable, private, result_serializer}; use proc_macro2::{Span, TokenStream as TokenStream2}; use quote::ToTokens; use syn::spanned::Spanned; @@ -103,24 +102,20 @@ impl AttrSigInfo { for attr in original_attrs.iter() { let attr_str = attr.path().to_token_stream().to_string(); match attr_str.as_str() { - #[allow(non_upper_case_globals)] - init => { + "init" => { let mut init_attr = InitAttr { ignore_state: false }; if let Some(state) = args.ignore_state { init_attr.ignore_state = state; } visitor.visit_init_attr(attr, &init_attr)?; } - #[allow(non_upper_case_globals)] - payable => { + "payable" => { visitor.visit_payable_attr(attr)?; } - #[allow(non_upper_case_globals)] - private => { + "private" => { visitor.visit_private_attr(attr)?; } - #[allow(non_upper_case_globals)] - result_serializer => { + "result_serializer" => { if args.borsh.is_some() && args.json.is_some() { return Err(Error::new( attr.span(), @@ -140,14 +135,13 @@ impl AttrSigInfo { } visitor.visit_result_serializer_attr(attr, &serializer)?; } - #[allow(non_upper_case_globals)] - handle_result => { + "handle_result" => { if let Some(value) = args.aliased { - let handle_result_attr = HandleResultAttr { check: value }; - visitor.visit_handle_result_attr(&handle_result_attr); + let handle_result = HandleResultAttr { check: value }; + visitor.visit_handle_result_attr(&handle_result); } else { - let handle_result_attr = HandleResultAttr { check: false }; - visitor.visit_handle_result_attr(&handle_result_attr); + let handle_result = HandleResultAttr { check: false }; + visitor.visit_handle_result_attr(&handle_result); } } _ => { diff --git a/near-sdk/Cargo.toml b/near-sdk/Cargo.toml index 1f854f87e..7488fe7bd 100644 --- a/near-sdk/Cargo.toml +++ b/near-sdk/Cargo.toml @@ -33,7 +33,6 @@ once_cell = { version = "1.17", default-features = false } near-account-id = { version="1.0.0", features = ["serde", "borsh"] } near-gas = { version = "0.2.3", features = ["serde", "borsh"] } near-token = { version = "0.2.0", features = ["serde", "borsh"] } -near-attribute-str = { path = "../near-attribute-str" } [target.'cfg(target_arch = "wasm32")'.dependencies] wee_alloc = { version = "0.4.5", default-features = false, optional = true } diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 3b81939b6..52db4cc8e 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -50,6 +50,8 @@ pub mod utils; pub use crate::utils::storage_key_impl::IntoStorageKey; pub use crate::utils::*; +pub mod near; + #[cfg(all(feature = "unit-testing", not(target_arch = "wasm32")))] pub mod test_utils; @@ -63,7 +65,6 @@ static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT; pub use base64; pub use borsh; pub use bs58; -pub use near_attribute_str::*; #[cfg(feature = "abi")] pub use schemars; pub use serde; diff --git a/near-sdk/src/near.rs b/near-sdk/src/near.rs new file mode 100644 index 000000000..0779dc958 --- /dev/null +++ b/near-sdk/src/near.rs @@ -0,0 +1,142 @@ +/// Initialization Methods inner #[near] 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: +/// # 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] annotation. +/// +/// 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] annotation. +/// +/// 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] 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] 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() {} From aeda1be4b188cf8ab0437c0e9329d4c662154ee7 Mon Sep 17 00:00:00 2001 From: Spring Chiu Date: Wed, 5 Jun 2024 22:27:15 +0800 Subject: [PATCH 3/5] chore: update test toolchain version and doc --- .github/workflows/test.yml | 2 +- near-sdk/src/near.rs | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ea0e1db5b..77b9be29b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -13,7 +13,7 @@ jobs: strategy: matrix: platform: [ubuntu-latest, macos-latest] - toolchain: [stable, 1.72.1] + toolchain: [stable, 1.78.0] steps: - uses: actions/checkout@v3 - name: "${{ matrix.toolchain }} with rustfmt, and wasm32" diff --git a/near-sdk/src/near.rs b/near-sdk/src/near.rs index 0779dc958..5e3de62a0 100644 --- a/near-sdk/src/near.rs +++ b/near-sdk/src/near.rs @@ -1,4 +1,4 @@ -/// Initialization Methods inner #[near] annotation. +/// Initialization Methods inner #[near] 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 @@ -25,7 +25,7 @@ /// ``` pub fn init() {} -/// Payable Methods inner #[near] annotation. +/// Payable Methods inner #[near] 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. /// @@ -53,7 +53,7 @@ pub fn init() {} /// ``` pub fn payable() {} -/// Private Methods inner #[near] annotation. +/// Private Methods inner #[near] 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. /// From 7c78c06d1a016e7c8596046bf5100095515efe4f Mon Sep 17 00:00:00 2001 From: Vlad Frolov Date: Thu, 20 Jun 2024 15:09:51 +0200 Subject: [PATCH 4/5] Hide the hack behind an internal __macro-docs feature flag --- near-sdk/Cargo.toml | 4 +++- near-sdk/src/lib.rs | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/near-sdk/Cargo.toml b/near-sdk/Cargo.toml index 7488fe7bd..795944a5a 100644 --- a/near-sdk/Cargo.toml +++ b/near-sdk/Cargo.toml @@ -73,5 +73,7 @@ unit-testing = ["near-vm-runner", "near-primitives-core", "near-primitives", "ne __abi-embed = ["near-sdk-macros/__abi-embed"] __abi-generate = ["abi", "near-sdk-macros/__abi-generate"] +__macro-docs = [] + [package.metadata.docs.rs] -features = ["unstable", "legacy"] +features = ["unstable", "legacy", "__macro-docs"] diff --git a/near-sdk/src/lib.rs b/near-sdk/src/lib.rs index 52db4cc8e..85da47a82 100644 --- a/near-sdk/src/lib.rs +++ b/near-sdk/src/lib.rs @@ -50,6 +50,7 @@ pub mod utils; pub use crate::utils::storage_key_impl::IntoStorageKey; pub use crate::utils::*; +#[cfg(feature = "__macro-docs")] pub mod near; #[cfg(all(feature = "unit-testing", not(target_arch = "wasm32")))] From b6fdac13c140c9e6fa9a3d1306190baa594ce33a Mon Sep 17 00:00:00 2001 From: Vlad Frolov Date: Thu, 20 Jun 2024 15:25:25 +0200 Subject: [PATCH 5/5] Added more cross-links --- near-sdk/src/near.rs | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/near-sdk/src/near.rs b/near-sdk/src/near.rs index 5e3de62a0..13a57426e 100644 --- a/near-sdk/src/near.rs +++ b/near-sdk/src/near.rs @@ -1,6 +1,11 @@ -/// Initialization Methods inner #[near] annotation. More details can be found [here](https://docs.near.org/sdk/rust/contract-structure/near-bindgen#initialization-methods) +//! `#[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: +/// 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 @@ -25,11 +30,11 @@ /// ``` pub fn init() {} -/// Payable Methods inner #[near] annotation. More details can be found [here](https://docs.near.org/sdk/rust/contract-structure/near-bindgen#payable-methods) +/// 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. +/// 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: +/// To declare a function as payable, use the `#[payable]` annotation as follows: /// # Examples /// /// ## Basic example @@ -53,9 +58,9 @@ pub fn init() {} /// ``` pub fn payable() {} -/// Private Methods inner #[near] annotation. More details can be found [here](https://docs.near.org/sdk/rust/contract-structure/near-bindgen#private-methods) +/// 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. +/// 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 @@ -81,7 +86,7 @@ pub fn payable() {} /// ``` pub fn private() {} -/// Result serialization inner #[near] annotation.. +/// Result serialization inner [`#[near]`](../attr.near.html) annotation. /// /// Only one of `borsh` or `json` can be specified. /// @@ -108,10 +113,10 @@ pub fn private() {} /// ``` pub fn result_serializer() {} -/// Support Result types regardless of how they're referred to inner #[near] annotation. +/// 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)] +/// 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 ///