From deb1e15ae4c60333636f0581e0f30d169d8c9a0a Mon Sep 17 00:00:00 2001
From: Linwei Shang <linwei.shang@dfinity.org>
Date: Thu, 15 Aug 2024 11:32:19 -0400
Subject: [PATCH] docs: clarify post_upgrade argument types (#508)

* Improve READMEs

* clarify post_upgrade arg type
---
 README.md                |  5 ++---
 src/ic-cdk/README.md     |  3 +--
 src/ic-cdk/src/macros.rs | 34 ++++++++++++++++++++++++++++++++--
 3 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 6aff8e388..2e0ecadc7 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ This repo provides libraries and tools to facilitate developing canisters in Rus
 - [`ic0`](src/ic0):
 Internet Computer System API binding.
 - [`ic-cdk`](src/ic-cdk):
-Internet Computer Canister Development Kit
+Internet Computer Canister Development Kit.
 - [`ic-cdk-bindgen`](src/ic-cdk-bindgen):
 Generate Rust bindings from Candid to make inter-canister calls.
 - [`ic-cdk-macros`](src/ic-cdk-macros):
@@ -53,8 +53,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 ic-cdk = "0.15"
-# Only necessary if you want to define Candid data types
-candid = "0.10" 
+candid = "0.10" # required if you want to define Candid data types
 ```
 
 Then in Rust source code:
diff --git a/src/ic-cdk/README.md b/src/ic-cdk/README.md
index 5fa3244e1..aaa8b802d 100644
--- a/src/ic-cdk/README.md
+++ b/src/ic-cdk/README.md
@@ -26,8 +26,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 ic-cdk = "0.15"
-# Only necessary if you want to define Candid data types
-candid = "0.10" 
+candid = "0.10" # required if you want to define Candid data types
 ```
 
 Then in Rust source code:
diff --git a/src/ic-cdk/src/macros.rs b/src/ic-cdk/src/macros.rs
index 733be8117..8c3162875 100644
--- a/src/ic-cdk/src/macros.rs
+++ b/src/ic-cdk/src/macros.rs
@@ -177,12 +177,15 @@ pub use ic_cdk_macros::update;
 /// }
 /// ```
 ///
-/// The init function may accept an argument, if that argument is a `CandidType`:
+/// The init function may accept an argument.
+///
+/// The argument must implement the `CandidType` trait.
+///
+/// And it should match the initialization parameters of the service constructor in the Candid interface.
 ///
 /// ```rust
 /// # use ic_cdk::init;
 /// # use candid::*;
-///
 /// #[derive(Clone, Debug, CandidType, Deserialize)]
 /// struct InitArg {
 ///     foo: u8,
@@ -197,6 +200,8 @@ pub use ic_cdk_macros::update;
 ///
 /// In this case, the argument will be read from `ic0.msg_arg_data_size/copy` and passed to the
 /// init function upon successful deserialization.
+///
+///
 /// Refer to the [`canister_init` Specification](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-init) for more information.
 pub use ic_cdk_macros::init;
 
@@ -240,6 +245,31 @@ pub use ic_cdk_macros::pre_upgrade;
 /// # unimplemented!()
 /// }
 /// ```
+///
+/// The post_upgrade function may accept an argument.
+///
+/// The argument must implement the `CandidType` trait.
+///
+/// And it should match the initialization parameters of the service constructor in the Candid interface.
+/// Therefore, the init function and the post_upgrade function should take the same argument type.
+///
+/// ```rust
+/// # use ic_cdk::post_upgrade;
+/// # use candid::*;
+/// #[derive(Clone, Debug, CandidType, Deserialize)]
+/// struct InitArg {
+///     foo: u8,
+/// }
+///
+/// #[post_upgrade]
+/// fn post_upgrade_function(arg: InitArg) {
+///     // ...
+/// # unimplemented!()
+/// }
+/// ```
+///
+/// In this case, the argument will be read from `ic0.msg_arg_data_size/copy` and passed to the
+/// post_upgrade function upon successful deserialization.
 pub use ic_cdk_macros::post_upgrade;
 
 /// Register the `canister_heartbeat` entry point of a canister.