docs: more informative README and call* methods (#454)

* docs: ic-cdk README * docs: README for macros * docs: call* methods * chore: bump version and changelog * fix: grammar and format * fix: a leftover lock change from other PR
dfinity · Jan 12, 2024 · edcbe3a · edcbe3a
1 parent 1da310b
commit edcbe3a
Show file tree

Hide file tree

Showing 12 changed files with 247 additions and 65 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git 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/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-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
@@ -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-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 provides 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
@@ -1,25 +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,
     missing_debug_implementations,
@@ -110,7 +89,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 +177,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/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
@@ -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,12 +22,13 @@ 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 }
 
 [dev-dependencies]
+anyhow = "1"
 rstest = "0.12.0"
 trybuild = "1.0"
 

diff --git a/src/ic-cdk/README.md b/src/ic-cdk/README.md
@@ -1,9 +1,80 @@
-# 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`.
+
+## Macros
+
+This library re-exports macros defined in `ic-cdk-macros` 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.
+* [Comprehensive examples](https://github.com/dfinity/examples/tree/master/rust): Illustrate how to build useful Rust canisters.
+
+## Manage Data Structure in Stable Memory
+
+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.