docs: clarify post_upgrade argument types (#508)

* Improve READMEs

* clarify post_upgrade arg type

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:

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:

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.