docs: Minor docs fixes (#674)

Author: adamspofford-dfinity

TROUBLESHOOTING.md

@@ -19,7 +19,7 @@ failed to select a version for `ic-cdk-executor` which could resolve this confli
 
 You have two incompatible versions of `ic-cdk` in your dependency tree. There are two common reasons for this.
 
-First, a dependency may be using an older (or newer) version of the CDK. Many versions are compatible with each other, but versions 0.17 and earlier are incompatible with versions 0.18 or later. You will have to wait for those dependencies to update, or patch them yourself.
+First, a dependency may be using an older (or newer) version of the CDK. Many versions are compatible with each other, but versions 0.17 and earlier are incompatible with version 0.18, and 0.18 is incompatible with 0.19 or later. You will have to wait for those dependencies to update, or patch them yourself.
 
 Second, a dependency may be using a nominally compatible version of the CDK, but you are using a GitHub prerelease of the CDK with `ic-cdk = { git =`. Git dependencies are automatically incompatible with everything, even if nothing changed. You will need to create a [patch table](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html) that replaces `ic-cdk` with a Git dependency at the same commit (you may also need to replace `ic-cdk-executor`).
 

ic-cdk-executor/README.md

@@ -0,0 +1,50 @@
+# `ic-cdk-executor`
+
+An async executor for [`ic-cdk`](https://docs.rs/ic-cdk). Most users should not use this crate directly. It is useful primarily for those who are writing their own CDK or a runtime host for non-Rust languages.
+
+## Contexts
+
+The expected boilerplate for a canister method or other entrypoint (*not* including callbacks) looks like this:
+
+```rust
+pub extern "C" fn function() {
+    in_tracking_executor_context(|| {
+        // method goes here
+    });
+}
+```
+
+The `in_tracking_executor_context` function permits you to call `spawn_*` functions. As little code as possible
+should exist outside the block, because `in_tracking_executor_context` additionally sets up the panic handler.
+
+The above applies to update contexts. Query contexts, including `inspect_message`, should use
+`in_tracking_query_executor_context`.
+
+The expected boilerplate for an inter-canister call callback looks like this:
+
+```rust
+unsafe extern "C" fn callback(env: usize) {
+    let method = unpack_env(env);
+    in_callback_executor_context_for(method, || {
+       // wake the call future
+    });
+}
+unsafe extern "C" fn cleanup(env: usize) {
+    let method = unpack_env(env);
+    in_trap_recovery_context_for(method, || {
+        cancel_all_tasks_attached_to_current_method();
+    });
+}
+```
+
+In async contexts, all scheduled tasks are run *after* the closure passed to the context function
+returns, but *before* the context function itself returns.
+
+The `method` parameter must be retrieved *before* making inter-canister calls via the `extend_current_method_context`
+function. Calling this function from the callback instead will trap.
+
+## Protection
+
+Tasks can be either *protected* or *migratory*. Protected tasks are attached to the method that spawned them,
+when awoken will not resume until that method continues, and will be canceled if the method returns before they complete.
+Migratory tasks are not attached to any method, and will resume in whatever method wakes them.

ic-cdk-executor/src/lib.rs

@@ -14,11 +14,11 @@
 //! }
 //! ```
 //!
-//! The `in_tracking_executor_context` function permits you to call `spawn_*` functions. As little code as possible
-//! should exist outside the block, because `in_tracking_executor_context` additionally sets up the panic handler.
+//! The [`in_tracking_executor_context`] function permits you to call `spawn_*` functions. As little code as possible
+//! should exist outside the block, because [`in_tracking_executor_context`] additionally sets up the panic handler.
 //!
-//! The above applies to update contexts. Query contexts, including `inspect_message`, should use
-//! `in_tracking_query_executor_context`.
+//! The above applies to update contexts. Query contexts, including `canister_inspect_message`, should use
+//! [`in_tracking_query_executor_context`].
 //!
 //! The expected boilerplate for an inter-canister call callback looks like this:
 //!

ic-cdk-executor/src/machinery.rs

@@ -93,7 +93,7 @@ impl Default for Task {
     }
 }
 
-/// Execute an update function in a context that allows calling [`spawn_protected`] and [`spawn_migratory`]
+/// Execute an update function in a context that allows calling [`spawn_protected`] and [`spawn_migratory`].
 pub fn in_tracking_executor_context<R>(f: impl FnOnce() -> R) -> R {
     setup_panic_hook();
     let method = METHODS.with_borrow_mut(|methods| methods.insert(MethodContext::new_update()));
@@ -143,7 +143,7 @@ pub fn in_callback_executor_context_for<R>(
     })
 }
 
-/// Enters a panic recovery context for calling [`cancel_all_tasks_attached_to_current_method`] in.
+/// Enters a trap/panic recovery context for calling [`cancel_all_tasks_attached_to_current_method`] in.
 pub fn in_trap_recovery_context_for<R>(method: MethodHandle, f: impl FnOnce() -> R) -> R {
     setup_panic_hook();
     enter_current_method(method, || {
@@ -398,8 +398,8 @@ pub fn spawn_migratory(f: impl Future<Output = ()> + 'static) -> TaskHandle {
 
 /// Spawns a task attached to the current method.
 ///
-/// When the task is awoken, if a different method is currently running, it will not run until the method
-/// it is attached to continues. If the attached method returns before the task completes, it will be canceled.
+/// When the task is awoken, if a different method is currently running, the task will not run until the method
+/// it is attached to continues. If the attached method returns before the task completes, the task will be canceled.
 pub fn spawn_protected(f: impl Future<Output = ()> + 'static) -> TaskHandle {
     setup_panic_hook();
     if is_recovering_from_trap() {

ic-cdk-timers/src/lib.rs

@@ -362,6 +362,13 @@ pub fn set_timer(delay: Duration, future: impl Future<Output = ()> + 'static) ->
 ///
 /// Note that timers are not persisted across canister upgrades.
 ///
+/// <div class="warning">
+///
+/// Interval timers should be *idempotent* with respect to the canister's state, as during heavy network load,
+/// timeouts may result in duplicate execution.
+///
+/// </div>
+///
 /// # Examples
 ///
 /// ```no_run