docs: Clarify Call to CallFuture conversion and fix minor inaccuracies (#669)

Author: lwshang

ic-cdk/Cargo.toml

@@ -40,6 +40,7 @@ thiserror.workspace = true
 [dev-dependencies]
 anyhow = "1"
 candid_parser.workspace = true
+futures = "0.3"
 rstest = "0.12.0"
 trybuild = "1.0"
 

ic-cdk/src/api.rs

@@ -167,9 +167,9 @@ pub fn canister_liquid_cycle_balance() -> u128 {
 /// Gets the status of the canister.
 ///
 /// The status is one of the following:
-///.- 1: Running
-///.- 2: Stopping
-///.- 3: Stopped
+/// - 1: Running
+/// - 2: Stopping
+/// - 3: Stopped
 pub fn canister_status() -> CanisterStatusCode {
     ic0::canister_status().into()
 }

ic-cdk/src/call.rs

@@ -103,19 +103,31 @@ pub use ic_error_types::RejectCode;
 /// # Execution
 ///
 /// A [`Call`] can be executed in two ways:
-/// - `.await`: convert into a future, execute asynchronously and wait for response.
-/// - [`oneway`][Self::oneway]: send a oneway call and not wait for the response.
+/// - **Asynchronously**: Convert to a [`CallFuture`] and await the response.
+///   - Direct approach: Use `.await` on the call (e.g., `call.await`).
+///   - Collective approach: Use [`IntoFuture::into_future`] to obtain futures explicitly,
+///     then combine them with `join!`, `select!`, or other combinators.
+/// - **One-way**: Send a call with [`oneway`][Self::oneway] when you don't need a response.
 ///
 /// ## Example
 ///
 /// ```rust, no_run
 /// # use ic_cdk::call::Call;
+/// # use candid::Principal;
 /// # async fn bar() {
-/// # let canister_id = ic_cdk::api::canister_self();
-/// # let method = "foo";
-/// let call = Call::bounded_wait(canister_id, method);
-/// let response = call.clone().await.unwrap();
-/// call.oneway().unwrap();
+/// # let canister_id : Principal = todo!();
+/// # let method: &str = todo!();
+/// # let canister_id1 : Principal = todo!();
+/// # let method1: &str = todo!();
+/// # let canister_id2 : Principal = todo!();
+/// # let method2: &str = todo!();
+/// let response = Call::bounded_wait(canister_id, method).await;
+/// let calls = vec![
+///   Call::bounded_wait(canister_id1, method1).into_future(),
+///   Call::bounded_wait(canister_id2, method2).into_future(),
+/// ];
+/// let responses = futures::future::join_all(calls).await;
+/// Call::bounded_wait(canister_id, method).oneway().unwrap();
 /// # }
 /// ```
 ///

ic-cdk/src/management_canister.rs

@@ -521,7 +521,7 @@ pub fn cost_http_request(arg: &HttpRequestArgs) -> u128 {
     ic0_cost_http_request(request_size, max_res_bytes)
 }
 
-/// Makes an HTTP outcall with a user-specified amount of cycles.
+/// Makes an HTTP outcall.
 ///
 /// **Unbounded-wait call**
 ///