Skip to content

Commit

Permalink
doc: split #[near(contract_state)] and #[near] doc
Browse files Browse the repository at this point in the history
  • Loading branch information
dj8yf0μl committed Feb 17, 2025
1 parent 3039096 commit a5bd55c
Showing 1 changed file with 62 additions and 47 deletions.
109 changes: 62 additions & 47 deletions near-sdk/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,15 +113,19 @@ extern crate quickcheck;
/// as generating the glue code to be a valid NEAR contract.
///
/// The macro is a syntactic sugar for [**near_bindgen**](near_bindgen) and expands to the [**near_bindgen**](near_bindgen) macro invocations.
/// Both of them share the same attributes, except for those that are explicitly marked as specific to the [**near**](near) macro. ([1](near#nearserializers-annotates-structsenums), [2](near#nearcontract_state-annotates-structsenums))
/// Both of them share the same attributes, except for those that are explicitly marked as specific to the [**near**](near) macro. ([1](near#nearcontract_state-annotates-structsenums), [2](near#nearserializers-annotates-structsenums))
///
/// # Attributes
///
/// ## `#[near(contract_state)]` (annotates structs/enums)
///
/// The attribute prepares a struct/enum to be a contract state. Only one contract state is allowed per crate.
///
/// A contract type is usually acompanied by an `impl` block, annotated with [`#[near]`](near#near-annotates-impl-blocks).
///
/// 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.**
///
/// `contract_state` is specific to the [near] macro only, not available for [near_bindgen].
///
/// ### Basic example
/// ```rust
Expand All @@ -135,28 +139,6 @@ extern crate quickcheck;
/// which usually comes paired with at least one **impl** block for the contract type,
/// annotated with a plain `#[near]` attribute:
///
/// ```rust
/// # use near_sdk::{near, log};
///
/// # #[near(contract_state)]
/// # pub struct Contract {
/// # greeting: String,
/// # }
/// #[near]
/// impl Contract {
/// // view method
/// pub fn get_greeting(&self) -> String {
/// self.greeting.clone()
/// }
///
/// // mutating method
/// pub fn set_greeting(&mut self, greeting: String) {
/// log!("Saving greeting: {greeting}");
/// self.greeting = greeting;
/// }
/// }
/// ```
///
/// ### Using SDK collections for storage
///
/// If contract state becomes large, collections from following modules can be used:
Expand Down Expand Up @@ -190,12 +172,10 @@ extern crate quickcheck;
///
/// * list of [**host functions**](collections#calls-to-host-functions-used-in-implementation) used for [`collections`] implementation
///
/// ### Implementation details and **host functions** calls used
/// ### Implementation details of `#[near(contract_state)]` macro and **host functions** calls used
///
/// If the details of [ABI](/~https://github.com/near/abi) generation layer are put aside, then the macro performs roughly the following:
///
/// #### inner workings of `#[near(contract_state)]` macro on struct/enum:
///
/// ```rust
/// # use near_sdk::near;
/// #[near(contract_state)]
Expand All @@ -213,7 +193,48 @@ extern crate quickcheck;
/// * calls [`env::setup_panic_hook`] host function
/// * calls [`env::value_return`] host function with bytes of `CONTRACT_SOURCE_METADATA` from step 2.
///
/// #### inner workings of `#[near]` macro on impl block:
/// ##### using [cargo-expand](https://crates.io/crates/cargo-expand) to view actual macro results
///
/// The above is an approximate description of what macro performs.
///
/// Running the following in a contract's crate is a way to introspect more details of its operation:
///
/// ```bash,ignore
/// cargo expand --lib --target wasm32-unknown-unknown
/// # this has additional code generated for ABI layer
/// cargo expand --lib --features near-sdk/__abi-generate
/// ```
/// ---
///
/// ## `#[near]` (annotates impl blocks)
///
/// This macro is used to define the code for view-only and mutating methods for contract types,
/// annotated by [`#[near(contract_state)]`](near#nearcontract_state-annotates-structsenums).
///
/// ### Basic example
/// ```rust
/// use near_sdk::{near, log};
///
/// # #[near(contract_state)]
/// # pub struct Contract {
/// # greeting: String,
/// # }
/// #[near]
/// impl Contract {
/// // view method
/// pub fn get_greeting(&self) -> String {
/// self.greeting.clone()
/// }
///
/// // mutating method
/// pub fn set_greeting(&mut self, greeting: String) {
/// log!("Saving greeting: {greeting}");
/// self.greeting = greeting;
/// }
/// }
/// ```
///
/// ### Implementation details of `#[near]` macro and **host functions** calls used
///
/// ```rust
/// # use near_sdk::near;
Expand All @@ -226,7 +247,9 @@ extern crate quickcheck;
/// pub fn mutating_method(&mut self, argument: String) { /* .. */ }
/// }
/// ```
/// ##### for a **view** method macro defines the following function:
///
/// ##### for above **view** method macro defines the following function:
///
/// ```rust,no_run
/// #[no_mangle]
/// pub extern "C" fn view_method() { /* .. */ }
Expand All @@ -235,14 +258,14 @@ extern crate quickcheck;
///
/// 1. calls [`env::setup_panic_hook`] host function
/// 2. calls [`env::state_read`] host function to load `Contract` into a `state` variable
/// 3. calls original `Contract::view_method(&state)` as defined in `#[near]` annotated block and saves
/// 3. calls original `Contract::view_method(&state)` as defined in `#[near]` annotated [impl block](near#implementation-details-of-near-macro-and-host-functions-calls-used) and saves
/// the returned value into a `result` variable
/// 4. calls [`serde_json::to_vec`] on obtained `result` and saves returned value to `serialized_result` variable
/// * `json` format can be changed to serializing with [`borsh::to_vec`] by using [`#[result_serializer(...)]`](`near#result_serializer-annotates-methods-of-a-type-in-its-impl-block`)
/// 5. if the `serialized_result` is an [`Result::Err`] error, then [`env::panic_str`] host function is called to signal result serialization error
/// 6. otherwise, if the `serialized_result` is a [`Result::Ok`], then [`env::value_return`] host function is called with unwrapped `serialized_result`
///
/// ##### for a **mutating** method macro defines the following function:
/// ##### for above **mutating** method macro defines the following function:
/// ```rust,no_run
/// #[no_mangle]
/// pub extern "C" fn mutating_method() { /* ..*/ }
Expand All @@ -251,30 +274,20 @@ extern crate quickcheck;
///
/// 1. calls [`env::setup_panic_hook`] host function
/// 2. calls [`env::input`] host function and saves it to `input` variable
/// 3. deserializes `Contract::mutating_method` arguments with [`serde_json::from_slice`] and saves it to `deserialized_input` variable
/// 3. deserializes `Contract::mutating_method` arguments by calling [`serde_json::from_slice`] on `input` variable and saves it to `deserialized_input` variable
/// * `json` format can be changed to deserializing with [`borsh::from_slice`] by using [`#[serializer(...)]`](`near#serializer-annotates-function-arguments`)
/// 4. if the `deserialized_input` is an [`Result::Err`] error, then [`env::panic_str`] host function is called to signal input deserialization error
/// 5. otherwise, if the `deserialized_input` is a [`Result::Ok`], `deserialized_input` is unwrapped and saved to `deserialized_input_success` variable
/// 6. calls [`env::state_read`] host function to load `Contract` into a `state` variable
/// 7. calls original `Contract::mutating_method(&mut state, deserialized_input_success.argument)` as defined in `#[near]` annotated block
/// 7. calls original `Contract::mutating_method(&mut state, deserialized_input_success.argument)` as defined in `#[near]` annotated [impl block](near#implementation-details-of-near-macro-and-host-functions-calls-used)
/// 8. calls [`env::state_write`] with `&state` as argument.
///
/// ##### using [cargo-expand](https://crates.io/crates/cargo-expand) to view actual macro results
///
/// The above is an approximate description of what macro performs.
///
/// Running the following in a contract's crate is a way to introspect more details of its operation:
///
/// ```bash,ignore
/// cargo expand --lib --target wasm32-unknown-unknown
/// # this has additional code generated for ABI layer
/// cargo expand --lib --features near-sdk/__abi-generate
/// ```
/// ---
///
/// ## `#[near(serializers=[...])` (annotates structs/enums)
///
/// 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.**
///
/// `serializers` is specific to the [near] macro only, not available for [near_bindgen].
///
/// ### Make struct/enum serializable with borsh
///
Expand Down Expand Up @@ -324,9 +337,11 @@ extern crate quickcheck;
///
/// ## `#[serializer(...)]` (annotates function arguments)
///
/// The attribute makes the function argument deserializable with either json or borsh. By default, json is used.
/// The attribute makes the function argument deserializable from [`Vec`]<[`u8`]> with either json or borsh. By default, json is used.
/// Please, note that all the arguments of the function should be using the same deserializer.
///
/// NOTE: a more correct name for the attribute would be `argument_deserializer`, but it's `serializer` for historic reasons.
///
/// ### Basic example
///
/// ```rust
Expand Down

0 comments on commit a5bd55c

Please sign in to comment.