From 33a24e6cfe016b1f018a58fa1f2ea85848850b5f Mon Sep 17 00:00:00 2001
From: Mark Hammond <mhammond@skippinet.com.au>
Date: Wed, 7 Aug 2024 09:28:28 -0400
Subject: [PATCH] Future cancellation docs and other minor doc tweaks. (#2206)

---
 docs/manual/src/futures.md                          | 10 ++++++++++
 .../src/tutorial/foreign_language_bindings.md       | 13 ++++++-------
 docs/manual/src/udl/ext_types.md                    |  8 ++++----
 3 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/docs/manual/src/futures.md b/docs/manual/src/futures.md
index 81d88b2a18..b2a5163d57 100644
--- a/docs/manual/src/futures.md
+++ b/docs/manual/src/futures.md
@@ -94,3 +94,13 @@ Use `uniffi_set_event_loop()` to handle this case.
 It should be called before the Rust code makes the async call and passed an eventloop to use.
 
 Note that `uniffi_set_event_loop` cannot be glob-imported because it's not part of the library's `__all__`.
+
+## Cancelling async code.
+
+We don't directly support cancellation in UniFFI even when the underlying platforms do.
+You should build your cancellation in a separate, library specific channel; for example, exposing a `cancel()` method that sets a flag that the library checks periodically.
+
+Cancellation can then be exposed in the API and be mapped to one of the error variants, or None/empty-vec/whatever makes sense.
+There's no builtin way to cancel a future, nor to cause/raise a platform native async cancellation error (eg, a swift `CancellationError`).
+
+See also https://github.com/mozilla/uniffi-rs/pull/1768.
diff --git a/docs/manual/src/tutorial/foreign_language_bindings.md b/docs/manual/src/tutorial/foreign_language_bindings.md
index b2ab9d3b5a..53a9f47f53 100644
--- a/docs/manual/src/tutorial/foreign_language_bindings.md
+++ b/docs/manual/src/tutorial/foreign_language_bindings.md
@@ -8,9 +8,9 @@ The next step is to have UniFFI generate source code for your foreign language.
 
 First, make sure you have installed all the [prerequisites](./Prerequisites.md).
 
-Ideally you would then run the `uniffi-bindgen` binary from the `uniffi` crate to generate your bindings.  However, this
-is only available with [Cargo nightly](https://doc.rust-lang.org/cargo/reference/unstable.html#artifact-dependencies).
-To work around this, you need to create a binary in your project that does the same thing.
+Ideally you would then run the `uniffi-bindgen` binary from the `uniffi` crate to generate your bindings,
+but if not on [Cargo nightly](https://doc.rust-lang.org/cargo/reference/unstable.html#artifact-dependencies),
+you need to create a binary in your project that does the same thing.
 
 Add the following to your `Cargo.toml`:
 
@@ -32,11 +32,10 @@ You can now run `uniffi-bindgen` from your project using `cargo run --features=u
 
 ### Multi-crate workspaces
 
-If your project consists of multiple crates in a Cargo workspace, then the process outlined above would require you
-creating a binary for each crate that uses UniFFI.  You can avoid this by creating a separate crate for running `uniffi-bindgen`:
-  - Name the crate `uniffi-bindgen`
+In a multiple crates workspace, you can create a separate crate for running `uniffi-bindgen`:
+  - Name the crate `uniffi-bindgen`, add it to your workspace.
   - Add this dependency to `Cargo.toml`: `uniffi = {version = "0.XX.0", features = ["cli"] }`
-  - Follow the steps from the previous section to add the `uniffi-bindgen` binary target
+  - As above, add the `uniffi-bindgen` binary target
 
 Then your can run `uniffi-bindgen` from any crate in your project using `cargo run -p uniffi-bindgen [args]`
 
diff --git a/docs/manual/src/udl/ext_types.md b/docs/manual/src/udl/ext_types.md
index 8e25c1aa70..65bfb66937 100644
--- a/docs/manual/src/udl/ext_types.md
+++ b/docs/manual/src/udl/ext_types.md
@@ -35,16 +35,16 @@ namespace app {
 ```
 
 Supported values:
-* "enum", "trait", "callback", "trait_with_foreign"
-* For records, either "record", "dictionary" or "struct"
-* For objects, either "object", "impl" or "interface"
+* Enums: `enum`
+* Records: `record`, `dictionary` or `struct`
+* Objects: `object`, `impl` or `interface`
+* Traits: `trait`, `callback` or `trait_with_foreign`
 
 eg:
 ```
 typedef enum MyEnum;
 typedef interface MyObject;
 ```
-etc.
 
 Note that in 0.28 and prior, we also supported this capability with a `[Rust=]` attribute.
 This attribute is deprecated and may be removed in a later version.