From 9e41965d7496fab22b0c16e7061a7d2288a5896c Mon Sep 17 00:00:00 2001 From: Linwei Shang Date: Fri, 12 Jan 2024 11:03:41 -0500 Subject: [PATCH 1/6] docs: ic-cdk README --- README.md | 9 ++++---- src/ic-cdk/README.md | 52 +++++++++++++++++++++++++++++++++++++++---- src/ic-cdk/src/lib.rs | 11 +++++---- 3 files changed, 58 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 2ca025e0c..cff587ef6 100644 --- a/README.md +++ b/README.md @@ -52,16 +52,17 @@ In Cargo.toml: crate-type = ["cdylib"] [dependencies] -candid = "0.10" # this version is required if you want to define Candid data types ic-cdk = "0.12" +# Only necessary if you want to define Candid data types +candid = "0.10" ``` -Then in your rust source code: +Then in Rust source code: ```rust #[ic_cdk::query] -fn print() { - ic_cdk::print("Hello World from DFINITY!"); +fn hello() -> String{ + "world".to_string() } ``` diff --git a/src/ic-cdk/README.md b/src/ic-cdk/README.md index e2687ee9d..0042fb430 100644 --- a/src/ic-cdk/README.md +++ b/src/ic-cdk/README.md @@ -1,9 +1,53 @@ -# ic-cdk - -**Internet Computer Canister Development Kit** - [![Documentation](https://docs.rs/ic-cdk/badge.svg)](https://docs.rs/ic-cdk/) [![Crates.io](https://img.shields.io/crates/v/ic-cdk.svg)](https://crates.io/crates/ic-cdk) [![License](https://img.shields.io/crates/l/ic-cdk.svg)](https://github.com/dfinity/cdk-rs/blob/main/src/ic-cdk/LICENSE) [![Downloads](https://img.shields.io/crates/d/ic-cdk.svg)](https://crates.io/crates/ic-cdk) [![CI](https://github.com/dfinity/cdk-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/dfinity/cdk-rs/actions/workflows/ci.yml) + +# ic-cdk + +Canister Developer Kit for the Internet Computer. + +## Background + +On the Internet Computer, smart contracts come in the form of canisters which are WebAssembly modules. + +Canisters expose entry points which can be called both by other canisters and by parties external to the IC. + +This library aims to provide a Rust-ergonomic abstraction to implement Canister entry points. + +## Using `ic-cdk` + +In Cargo.toml: + +```toml +[lib] +crate-type = ["cdylib"] + +[dependencies] +ic-cdk = "0.12" +# Only necessary if you want to define Candid data types +candid = "0.10" +``` + +Then in Rust source code: + +```rust +#[ic_cdk::query] +fn hello() -> String{ + "world".to_string() +} +``` + +This will register a **query** entry point named `hello`. + +## More examples + +* [Basic examples](https://github.com/dfinity/cdk-rs/tree/main/examples): Demonstrate usage of `ic-cdk` API. +* [Comprehensive examples](https://github.com/dfinity/examples/tree/master/rust): Illustrate how to build useful Rust canisters. + +## Manage Data Structure in Stable Memory + +Using `ic_cdk::storage::{stable_save, stable_restore}` API is easy but it doesn't scale well. + +[`ic-stable-structures`](https://crates.io/crates/ic-stable-structures) is recommended when you are dealing with multiple data structures with larger datasets. diff --git a/src/ic-cdk/src/lib.rs b/src/ic-cdk/src/lib.rs index b15390382..0a139be90 100644 --- a/src/ic-cdk/src/lib.rs +++ b/src/ic-cdk/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + #![warn( elided_lifetimes_in_paths, missing_debug_implementations, @@ -8,12 +10,6 @@ )] #![cfg_attr(docsrs, feature(doc_cfg))] -//! This crate provides building blocks for developing Internet Computer canisters. -//! -//! You can check the [Internet Computer Specification]( -//! https://smartcontracts.org/docs/interface-spec/index.html#system-api-imports) -//! for a full list of the system API functions. - #[cfg(target_feature = "atomics")] compile_error!("This version of the CDK does not support multithreading."); @@ -27,8 +23,11 @@ pub mod storage; use std::sync::atomic::{AtomicBool, Ordering}; +#[doc(inline)] pub use api::call::call; +#[doc(inline)] pub use api::call::notify; +#[doc(inline)] pub use api::{caller, id, print, trap}; static DONE: AtomicBool = AtomicBool::new(false); From 81da52aca9fa1c0d687e586a7cd45f7a881ed908 Mon Sep 17 00:00:00 2001 From: Linwei Shang Date: Fri, 12 Jan 2024 11:27:24 -0500 Subject: [PATCH 2/6] docs: README for macros --- src/ic-cdk-macros/README.md | 31 ++++++++++++++++++++++++++----- src/ic-cdk-macros/src/lib.rs | 26 +++----------------------- src/ic-cdk/README.md | 27 +++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 28 deletions(-) diff --git a/src/ic-cdk-macros/README.md b/src/ic-cdk-macros/README.md index 95c912264..1961ce78e 100644 --- a/src/ic-cdk-macros/README.md +++ b/src/ic-cdk-macros/README.md @@ -1,11 +1,32 @@ -# ic-cdk-macros - -**Internet Computer Canister Development Kit** - [![Documentation](https://docs.rs/ic-cdk-macros/badge.svg)](https://docs.rs/ic-cdk-macros/) [![Crates.io](https://img.shields.io/crates/v/ic-cdk-macros.svg)](https://crates.io/crates/ic-cdk-macros) [![License](https://img.shields.io/crates/l/ic-cdk-macros.svg)](https://github.com/dfinity/cdk-rs/blob/main/src/ic-cdk-macros/LICENSE) [![Downloads](https://img.shields.io/crates/d/ic-cdk-macros.svg)](https://crates.io/crates/ic-cdk-macros) [![CI](https://github.com/dfinity/cdk-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/dfinity/cdk-rs/actions/workflows/ci.yml) -This crate provides attribute macros, with which you can annotate regular rust functions to be public interfaces of a canister. +# ic-cdk-macros + +This crate provide a set of macros to facilitate canister development. + +The macros fall into two categories: + +* To register functions as canister entry points +* To export Candid definitions + +## Register functions as canister entry points + +These macros are directly related to the [Internet Computer Specification](https://internetcomputer.org/docs/current/references/ic-interface-spec#entry-points). + +* [`init`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.init.html) +* [`pre_upgrade`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.pre_upgrade.html) +* [`post_upgrade`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.post_upgrade.html) +* [`inspect_message`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.inspect_message.html) +* [`heartbeat`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.heartbeat.html) +* [`update`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.update.html) +* [`query`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.query.html) + +## Export Candid definitions + +* [`export_candid`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/macro.export_candid.html) + +Check [Generating Candid files for Rust canisters](https://internetcomputer.org/docs/current/developer-docs/backend/candid/generating-candid/) for more details. diff --git a/src/ic-cdk-macros/src/lib.rs b/src/ic-cdk-macros/src/lib.rs index a4a25d58c..8cf1179ae 100644 --- a/src/ic-cdk-macros/src/lib.rs +++ b/src/ic-cdk-macros/src/lib.rs @@ -1,24 +1,4 @@ -//! This crate provide a set of attribute macros to facilitate canister development. -//! -//! The macros fall into two categories: -//! * To register functions as canister entry points -//! * To export candid definitions -//! -//! ## Register functions as canister entry points -//! -//! These macros are directly related to the [Internet Computer Specification](https://smartcontracts.org/docs/interface-spec/index.html#_entry_points). -//! -//! * [`init`](attr.init.html) -//! * [`pre_upgrade`](attr.pre_upgrade.html) -//! * [`post_upgrade`](attr.post_upgrade.html) -//! * [`inspect_message`](attr.inspect_message.html) -//! * [`heartbeat`](attr.heartbeat.html) -//! * [`update`](attr.update.html) -//! * [`query`](attr.query.html) -//! -//! ## Export candid definitions -//! -//! * [`export_candid`](attr.export_candid.html) +#![doc = include_str!("../README.md")] #![warn( elided_lifetimes_in_paths, @@ -110,7 +90,7 @@ pub fn export_candid(input: TokenStream) -> TokenStream { /// } /// ``` /// -/// If you want to hide this method in the Candid generated by [export_candid], +/// If you want to hide this method in the Candid generated by [export_candid!], /// you will need to set `hidden` to `true`. The entry point still exists in the canister. /// /// ```rust @@ -198,7 +178,7 @@ pub fn query(attr: TokenStream, item: TokenStream) -> TokenStream { /// } /// ``` /// -/// If you want to hide this method in the Candid generated by [export_candid], +/// If you want to hide this method in the Candid generated by [export_candid!], /// you will need to set `hidden` to `true`. The entry point still exists in the canister. /// /// ```rust diff --git a/src/ic-cdk/README.md b/src/ic-cdk/README.md index 0042fb430..7125e802e 100644 --- a/src/ic-cdk/README.md +++ b/src/ic-cdk/README.md @@ -41,6 +41,33 @@ fn hello() -> String{ This will register a **query** entry point named `hello`. +## Macros + +This library re-export macros defined in `ic-cdk-marcos` crate. + +The macros fall into two categories: + +* To register functions as canister entry points +* To export Candid definitions + +### Register functions as canister entry points + +These macros are directly related to the [Internet Computer Specification](https://internetcomputer.org/docs/current/references/ic-interface-spec#entry-points). + +* [`init`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.init.html) +* [`pre_upgrade`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.pre_upgrade.html) +* [`post_upgrade`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.post_upgrade.html) +* [`inspect_message`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.inspect_message.html) +* [`heartbeat`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.heartbeat.html) +* [`update`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.update.html) +* [`query`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/attr.query.html) + +### Export Candid definitions + +* [`export_candid`](https://docs.rs/ic-cdk-macros/latest/ic_cdk_macros/macro.export_candid.html) + +Check [Generating Candid files for Rust canisters](https://internetcomputer.org/docs/current/developer-docs/backend/candid/generating-candid/) for more details. + ## More examples * [Basic examples](https://github.com/dfinity/cdk-rs/tree/main/examples): Demonstrate usage of `ic-cdk` API. From c6748415c569a81272121158cd1dd9dec8b05517 Mon Sep 17 00:00:00 2001 From: Linwei Shang Date: Fri, 12 Jan 2024 15:34:56 -0500 Subject: [PATCH 3/6] docs: call* methods --- Cargo.lock | 1 + src/ic-cdk-macros/src/lib.rs | 1 - src/ic-cdk/Cargo.toml | 1 + src/ic-cdk/src/api/call.rs | 127 ++++++++++++++++++++++++++++++----- src/ic-cdk/src/lib.rs | 1 - 5 files changed, 114 insertions(+), 17 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index bc86495f2..faad869e8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -877,6 +877,7 @@ checksum = "9a3a5bfb195931eeb336b2a7b4d761daec841b97f947d34394601737a7bba5e4" name = "ic-cdk" version = "0.12.0" dependencies = [ + "anyhow", "candid", "ic-cdk-macros", "ic0", diff --git a/src/ic-cdk-macros/src/lib.rs b/src/ic-cdk-macros/src/lib.rs index 8cf1179ae..0aa73b91f 100644 --- a/src/ic-cdk-macros/src/lib.rs +++ b/src/ic-cdk-macros/src/lib.rs @@ -1,5 +1,4 @@ #![doc = include_str!("../README.md")] - #![warn( elided_lifetimes_in_paths, missing_debug_implementations, diff --git a/src/ic-cdk/Cargo.toml b/src/ic-cdk/Cargo.toml index 42bc64d90..55c925218 100644 --- a/src/ic-cdk/Cargo.toml +++ b/src/ic-cdk/Cargo.toml @@ -28,6 +28,7 @@ serde_bytes.workspace = true slotmap = { workspace = true, optional = true } [dev-dependencies] +anyhow = "1" rstest = "0.12.0" trybuild = "1.0" diff --git a/src/ic-cdk/src/api/call.rs b/src/ic-cdk/src/api/call.rs index c335e459f..a2322c3ac 100644 --- a/src/ic-cdk/src/api/call.rs +++ b/src/ic-cdk/src/api/call.rs @@ -280,7 +280,21 @@ pub fn notify_raw( } } -/// Similar to `call`, but without serialization. +/// Performs an asynchronous call to another canister and pay cycles at the same time. +/// +/// Treating arguments and returns as raw bytes. No data serialization and deserialization. +/// +/// # Example +/// +/// It can be called: +/// +/// ```rust +/// # use ic_cdk::api::call::call_raw; +/// # fn callee_canister() -> candid::Principal { unimplemented!() } +/// async fn call_add_user() -> Vec{ +/// call_raw(callee_canister(), "add_user", b"abcd", 1_000_000u64).await.unwrap() +/// } +/// ``` pub fn call_raw<'a, T: AsRef<[u8]> + Send + Sync + 'a>( id: Principal, method: &str, @@ -290,7 +304,21 @@ pub fn call_raw<'a, T: AsRef<[u8]> + Send + Sync + 'a>( call_raw_internal(id, method, args_raw, payment.into()) } -/// Similar to `call128`, but without serialization. +/// Performs an asynchronous call to another canister and pay cycles (in `u128`) at the same time. +/// +/// Treating arguments and returns as raw bytes. No data serialization and deserialization. +/// +/// # Example +/// +/// It can be called: +/// +/// ```rust +/// # use ic_cdk::api::call::call_raw128; +/// # fn callee_canister() -> candid::Principal { unimplemented!() } +/// async fn call_add_user() -> Vec{ +/// call_raw128(callee_canister(), "add_user", b"abcd", 1_000_000u128).await.unwrap() +/// } +/// ``` pub fn call_raw128<'a, T: AsRef<[u8]> + Send + Sync + 'a>( id: Principal, method: &str, @@ -328,14 +356,35 @@ fn decoder_error_to_reject(err: candid::error::Error) -> (RejectionCode, Stri ) } -/// Performs an asynchronous call to another canister using the [System API](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-call). +/// Performs an asynchronous call to another canister. +/// +/// # Example +/// +/// Assuming that the callee canister has following interface: +/// +/// ```text +/// service : { +/// add_user(name: Text) -> (nat64); +/// } +/// ``` +/// +/// It can be called: +/// +/// ```rust +/// # use ic_cdk::api::call::call; +/// # fn callee_canister() -> candid::Principal { unimplemented!() } +/// async fn call_add_user() -> u64{ +/// let (user_id,) = call(callee_canister(), "add_user", ("Alice".to_string(),)).await.unwrap(); +/// user_id +/// } +/// ``` /// -/// If the reply payload is not a valid encoding of the expected type `T`, -/// the call results in [RejectionCode::CanisterError] error. +/// # Note /// -/// Note that the asynchronous call must be awaited -/// in order for the inter-canister call to be made -/// using the [System API](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-call). +/// * Both argument and return types are tuples even if it has only one value, e.g `(user_id,)`, `("Alice".to_string(),)`. +/// * The type annotation on return type is required. Or the return type can be inferred from the context. +/// * The asynchronous call must be awaited in order for the inter-canister call to be made. +/// * If the reply payload is not a valid encoding of the expected type `T`, the call results in [RejectionCode::CanisterError] error. pub fn call ArgumentDecoder<'a>>( id: Principal, method: &str, @@ -351,9 +400,33 @@ pub fn call ArgumentDecoder<'a>>( /// Performs an asynchronous call to another canister and pay cycles at the same time. /// -/// Note that the asynchronous call must be awaited -/// in order for the inter-canister call to be made -/// using the [System API](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-call). +/// # Example +/// +/// Assuming that the callee canister has following interface: +/// +/// ```text +/// service : { +/// add_user(name: Text) -> (nat64); +/// } +/// ``` +/// +/// It can be called: +/// +/// ```rust +/// # use ic_cdk::api::call::call_with_payment; +/// # fn callee_canister() -> candid::Principal { unimplemented!() } +/// async fn call_add_user() -> u64{ +/// let (user_id,) = call_with_payment(callee_canister(), "add_user", ("Alice".to_string(),), 1_000_000u64).await.unwrap(); +/// user_id +/// } +/// ``` +/// +/// # Note +/// +/// * Both argument and return types are tuples even if it has only one value, e.g `(user_id,)`, `("Alice".to_string(),)`. +/// * The type annotation on return type is required. Or the return type can be inferred from the context. +/// * The asynchronous call must be awaited in order for the inter-canister call to be made. +/// * If the reply payload is not a valid encoding of the expected type `T`, the call results in [RejectionCode::CanisterError] error. pub fn call_with_payment ArgumentDecoder<'a>>( id: Principal, method: &str, @@ -368,11 +441,35 @@ pub fn call_with_payment ArgumentDecoder<'a>>( } } -/// Performs an asynchronous call to another canister and pay cycles at the same time. +/// Performs an asynchronous call to another canister and pay cycles (in `u128`) at the same time. +/// +/// # Example +/// +/// Assuming that the callee canister has following interface: +/// +/// ```text +/// service : { +/// add_user(name: Text) -> (nat64); +/// } +/// ``` +/// +/// It can be called: +/// +/// ```rust +/// # use ic_cdk::api::call::call_with_payment128; +/// # fn callee_canister() -> candid::Principal { unimplemented!() } +/// async fn call_add_user() -> u64{ +/// let (user_id,) = call_with_payment128(callee_canister(), "add_user", ("Alice".to_string(),), 1_000_000u128).await.unwrap(); +/// user_id +/// } +/// ``` +/// +/// # Note /// -/// Note that the asynchronous call must be awaited -/// in order for the inter-canister call to be made -/// using the [System API](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-call). +/// * Both argument and return types are tuples even if it has only one value, e.g `(user_id,)`, `("Alice".to_string(),)`. +/// * The type annotation on return type is required. Or the return type can be inferred from the context. +/// * The asynchronous call must be awaited in order for the inter-canister call to be made. +/// * If the reply payload is not a valid encoding of the expected type `T`, the call results in [RejectionCode::CanisterError] error. pub fn call_with_payment128 ArgumentDecoder<'a>>( id: Principal, method: &str, diff --git a/src/ic-cdk/src/lib.rs b/src/ic-cdk/src/lib.rs index 0a139be90..20492aeff 100644 --- a/src/ic-cdk/src/lib.rs +++ b/src/ic-cdk/src/lib.rs @@ -1,5 +1,4 @@ #![doc = include_str!("../README.md")] - #![warn( elided_lifetimes_in_paths, missing_debug_implementations, From 978d5899c368f73801fae385023c29e91f4e82f0 Mon Sep 17 00:00:00 2001 From: Linwei Shang Date: Fri, 12 Jan 2024 15:42:21 -0500 Subject: [PATCH 4/6] chore: bump version and changelog --- Cargo.lock | 4 ++-- Cargo.toml | 2 +- src/ic-cdk-macros/CHANGELOG.md | 8 +++++++- src/ic-cdk-macros/Cargo.toml | 2 +- src/ic-cdk/CHANGELOG.md | 7 +++++++ src/ic-cdk/Cargo.toml | 4 ++-- 6 files changed, 20 insertions(+), 7 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index faad869e8..8e1523842 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -875,7 +875,7 @@ checksum = "9a3a5bfb195931eeb336b2a7b4d761daec841b97f947d34394601737a7bba5e4" [[package]] name = "ic-cdk" -version = "0.12.0" +version = "0.12.1" dependencies = [ "anyhow", "candid", @@ -914,7 +914,7 @@ dependencies = [ [[package]] name = "ic-cdk-macros" -version = "0.8.3" +version = "0.8.4" dependencies = [ "candid", "proc-macro2", diff --git a/Cargo.toml b/Cargo.toml index dbcbf3474..f7f2c2a5a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -20,7 +20,7 @@ opt-level = 'z' [workspace.dependencies] ic0 = { path = "src/ic0", version = "0.21.1" } -ic-cdk = { path = "src/ic-cdk", version = "0.12.0" } +ic-cdk = { path = "src/ic-cdk", version = "0.12.1" } ic-cdk-timers = { path = "src/ic-cdk-timers", version = "0.6.0" } candid = "0.10" diff --git a/src/ic-cdk-macros/CHANGELOG.md b/src/ic-cdk-macros/CHANGELOG.md index 4f9ea7b86..f13441383 100644 --- a/src/ic-cdk-macros/CHANGELOG.md +++ b/src/ic-cdk-macros/CHANGELOG.md @@ -6,7 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [unreleased] -## [0.8.2] - 2023-12-13 +## [0.8.4] - 2024-01-12 + +### Fixed + +- The README file is now more informative and used as the front page of the doc site. + +## [0.8.3] - 2023-12-13 ### Added diff --git a/src/ic-cdk-macros/Cargo.toml b/src/ic-cdk-macros/Cargo.toml index ac360399a..82915a14f 100644 --- a/src/ic-cdk-macros/Cargo.toml +++ b/src/ic-cdk-macros/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "ic-cdk-macros" -version = "0.8.3" # no need to sync with ic-cdk +version = "0.8.4" # no need to sync with ic-cdk authors.workspace = true edition.workspace = true license.workspace = true diff --git a/src/ic-cdk/CHANGELOG.md b/src/ic-cdk/CHANGELOG.md index bbc4681c2..d1f4b6954 100644 --- a/src/ic-cdk/CHANGELOG.md +++ b/src/ic-cdk/CHANGELOG.md @@ -6,12 +6,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [unreleased] +## [0.12.1] - 2024-01-12 + ### Changed - Add "reserved cycles" fields to the management canister API: (#449) - `reserved_cycles` to `CanisterStatusResponse` - `reserved_cycles_limit` to `CanisterSettings` and `DefiniteCanisterSettings` +### Fixed + +- The README file is now more informative and used as the front page of the doc site. +- The `call*` methods are documented with examples and notes. + ## [0.12.0] - 2023-11-23 ### Changed diff --git a/src/ic-cdk/Cargo.toml b/src/ic-cdk/Cargo.toml index 55c925218..22d7ae18a 100644 --- a/src/ic-cdk/Cargo.toml +++ b/src/ic-cdk/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "ic-cdk" -version = "0.12.0" +version = "0.12.1" authors.workspace = true edition.workspace = true license.workspace = true @@ -22,7 +22,7 @@ include = ["src", "Cargo.toml", "LICENSE", "README.md"] [dependencies] candid.workspace = true ic0.workspace = true -ic-cdk-macros = { path = "../ic-cdk-macros", version = "0.8.3" } +ic-cdk-macros = { path = "../ic-cdk-macros", version = "0.8.4" } serde.workspace = true serde_bytes.workspace = true slotmap = { workspace = true, optional = true } From 74e86ab8b08e4cff06c38b48a6849a2437a0a6a0 Mon Sep 17 00:00:00 2001 From: Linwei Shang Date: Fri, 12 Jan 2024 17:03:03 -0500 Subject: [PATCH 5/6] fix: grammar and format --- src/ic-cdk-macros/README.md | 2 +- src/ic-cdk/README.md | 6 +++--- src/ic-cdk/src/api/call.rs | 21 ++++++++++----------- 3 files changed, 14 insertions(+), 15 deletions(-) diff --git a/src/ic-cdk-macros/README.md b/src/ic-cdk-macros/README.md index 1961ce78e..c7dd633dc 100644 --- a/src/ic-cdk-macros/README.md +++ b/src/ic-cdk-macros/README.md @@ -6,7 +6,7 @@ # ic-cdk-macros -This crate provide a set of macros to facilitate canister development. +This crate provides a set of macros to facilitate canister development. The macros fall into two categories: diff --git a/src/ic-cdk/README.md b/src/ic-cdk/README.md index 7125e802e..d3ec7ea20 100644 --- a/src/ic-cdk/README.md +++ b/src/ic-cdk/README.md @@ -34,7 +34,7 @@ Then in Rust source code: ```rust #[ic_cdk::query] -fn hello() -> String{ +fn hello() -> String { "world".to_string() } ``` @@ -43,7 +43,7 @@ This will register a **query** entry point named `hello`. ## Macros -This library re-export macros defined in `ic-cdk-marcos` crate. +This library re-exports macros defined in `ic-cdk-macros` crate. The macros fall into two categories: @@ -75,6 +75,6 @@ Check [Generating Candid files for Rust canisters](https://internetcomputer.org/ ## Manage Data Structure in Stable Memory -Using `ic_cdk::storage::{stable_save, stable_restore}` API is easy but it doesn't scale well. +Using the `ic_cdk::storage::{stable_save, stable_restore}` API is easy but it doesn't scale well. [`ic-stable-structures`](https://crates.io/crates/ic-stable-structures) is recommended when you are dealing with multiple data structures with larger datasets. diff --git a/src/ic-cdk/src/api/call.rs b/src/ic-cdk/src/api/call.rs index a2322c3ac..c43a30d2e 100644 --- a/src/ic-cdk/src/api/call.rs +++ b/src/ic-cdk/src/api/call.rs @@ -282,7 +282,7 @@ pub fn notify_raw( /// Performs an asynchronous call to another canister and pay cycles at the same time. /// -/// Treating arguments and returns as raw bytes. No data serialization and deserialization. +/// Treats arguments and returns as raw bytes. No data serialization and deserialization is performed. /// /// # Example /// @@ -291,7 +291,7 @@ pub fn notify_raw( /// ```rust /// # use ic_cdk::api::call::call_raw; /// # fn callee_canister() -> candid::Principal { unimplemented!() } -/// async fn call_add_user() -> Vec{ +/// async fn call_add_user() -> Vec{ /// call_raw(callee_canister(), "add_user", b"abcd", 1_000_000u64).await.unwrap() /// } /// ``` @@ -306,8 +306,7 @@ pub fn call_raw<'a, T: AsRef<[u8]> + Send + Sync + 'a>( /// Performs an asynchronous call to another canister and pay cycles (in `u128`) at the same time. /// -/// Treating arguments and returns as raw bytes. No data serialization and deserialization. -/// +/// Treats arguments and returns as raw bytes. No data serialization and deserialization is performed. /// # Example /// /// It can be called: @@ -315,7 +314,7 @@ pub fn call_raw<'a, T: AsRef<[u8]> + Send + Sync + 'a>( /// ```rust /// # use ic_cdk::api::call::call_raw128; /// # fn callee_canister() -> candid::Principal { unimplemented!() } -/// async fn call_add_user() -> Vec{ +/// async fn call_add_user() -> Vec{ /// call_raw128(callee_canister(), "add_user", b"abcd", 1_000_000u128).await.unwrap() /// } /// ``` @@ -364,7 +363,7 @@ fn decoder_error_to_reject(err: candid::error::Error) -> (RejectionCode, Stri /// /// ```text /// service : { -/// add_user(name: Text) -> (nat64); +/// add_user: (name: text) -> (nat64); /// } /// ``` /// @@ -373,7 +372,7 @@ fn decoder_error_to_reject(err: candid::error::Error) -> (RejectionCode, Stri /// ```rust /// # use ic_cdk::api::call::call; /// # fn callee_canister() -> candid::Principal { unimplemented!() } -/// async fn call_add_user() -> u64{ +/// async fn call_add_user() -> u64 { /// let (user_id,) = call(callee_canister(), "add_user", ("Alice".to_string(),)).await.unwrap(); /// user_id /// } @@ -406,7 +405,7 @@ pub fn call ArgumentDecoder<'a>>( /// /// ```text /// service : { -/// add_user(name: Text) -> (nat64); +/// add_user: (name: text) -> (nat64); /// } /// ``` /// @@ -415,7 +414,7 @@ pub fn call ArgumentDecoder<'a>>( /// ```rust /// # use ic_cdk::api::call::call_with_payment; /// # fn callee_canister() -> candid::Principal { unimplemented!() } -/// async fn call_add_user() -> u64{ +/// async fn call_add_user() -> u64 { /// let (user_id,) = call_with_payment(callee_canister(), "add_user", ("Alice".to_string(),), 1_000_000u64).await.unwrap(); /// user_id /// } @@ -449,7 +448,7 @@ pub fn call_with_payment ArgumentDecoder<'a>>( /// /// ```text /// service : { -/// add_user(name: Text) -> (nat64); +/// add_user: (name: text) -> (nat64); /// } /// ``` /// @@ -458,7 +457,7 @@ pub fn call_with_payment ArgumentDecoder<'a>>( /// ```rust /// # use ic_cdk::api::call::call_with_payment128; /// # fn callee_canister() -> candid::Principal { unimplemented!() } -/// async fn call_add_user() -> u64{ +/// async fn call_add_user() -> u64 { /// let (user_id,) = call_with_payment128(callee_canister(), "add_user", ("Alice".to_string(),), 1_000_000u128).await.unwrap(); /// user_id /// } From 5b43e70e0823c90651b5b8ca761a0b9d18bdb516 Mon Sep 17 00:00:00 2001 From: Linwei Shang Date: Fri, 12 Jan 2024 17:06:26 -0500 Subject: [PATCH 6/6] fix: a leftover lock change from other PR --- Cargo.lock | 1 + 1 file changed, 1 insertion(+) diff --git a/Cargo.lock b/Cargo.lock index 8e1523842..bc0817a93 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -940,6 +940,7 @@ dependencies = [ name = "ic-certified-map" version = "0.4.0" dependencies = [ + "bincode", "candid", "hex", "ic-cdk",