From f3e045ddf4ee5c589078912faa4fefbc106a02e1 Mon Sep 17 00:00:00 2001
From: Lukasz Anforowicz <anforowicz@users.noreply.github.com>
Date: Fri, 1 Dec 2023 08:24:59 +0000
Subject: [PATCH] Chromium: Enumerate automation benefits of `cxx` + other
 minor tweaks. (#1524)

---
 src/chromium/interoperability-with-cpp.md     | 31 ++++++++++++++++---
 .../example-bindings.md                       | 12 +++----
 2 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/src/chromium/interoperability-with-cpp.md b/src/chromium/interoperability-with-cpp.md
index b93ab874..c6334b93 100644
--- a/src/chromium/interoperability-with-cpp.md
+++ b/src/chromium/interoperability-with-cpp.md
@@ -19,9 +19,32 @@ See the [CXX tutorial][1] for a full example of using this.
 <details>
 
 Talk through the diagram. Explain that behind the scenes, this is doing
-just the same as you previously did --- but by programmatically ensuring that
-the C++ and Rust sides match, cxx can ensure there aren't obvious errors
-with object lifetimes, string lengths, etc. It reduces lots of fiddly
-boilerplate and the resulting code feels more "natural".
+just the same as you previously did. Point out that automating the process has
+the following benefits:
+
+* The tool guarantees that the C++ and Rust sides match
+  (e.g. you get compile errors if the `#[cxx::bridge]` doesn't match the actual
+  C++ or Rust definitions, but with out-of-sync manual bindings you'd get
+  Undefined Behavior)
+* The tool automates generation of FFI thunks (small, C-ABI-compatible, free
+  functions) for non-C features
+  (e.g. enabling FFI calls into Rust or C++ methods;
+  manual bindings would require authoring such top-level, free functions
+  manually)
+* The tool and the library can handle a set of core types - for example:
+    - `&[T]` can be passed across the FFI boundary, even though it doesn't
+      guarantee any particular ABI or memory layout. With manual bindings
+      `std::span<T>` / `&[T]` have to be manually destructured and rebuilt out
+      of a pointer and length - this is error-prone given that each language
+      represents empty slices slightly differently)
+    - Smart pointers like `std::unique_ptr<T>`,
+      `std::shared_ptr<T>`, and/or `Box` are natively supported. With manual
+      bindings, one would have to pass C-ABI-compatible raw pointers, which
+      would increase lifetime and memory-safety risks.
+    - `rust::String` and `CxxString` types understand and maintain differences
+      in string representation across the languages (e.g. `rust::String::lossy`
+      can build a Rust string from non-UTF8 input and `rust::String::c_str`
+      can NUL-terminate a string).
 
 </details>
+
diff --git a/src/chromium/interoperability-with-cpp/example-bindings.md b/src/chromium/interoperability-with-cpp/example-bindings.md
index da49de04..db10d7aa 100644
--- a/src/chromium/interoperability-with-cpp/example-bindings.md
+++ b/src/chromium/interoperability-with-cpp/example-bindings.md
@@ -1,23 +1,23 @@
 # Example bindings
 
-cxx requires you to declare the whole C++/Rust boundary in one of your `.rs`
-files. For instance:
+cxx requires that the whole C++/Rust boundary is declared in `cxx::bridge`
+"modules" inside `.rs` source code.
 
 ```rust,ignore
 {{#include ../../../third_party/cxx/book/snippets.rs:cxx_overview}}
 ```
 
 <details>
+
 Point out:
 
 * Native support for C++'s `std::unique_ptr` in Rust
 * Native support for Rust slices in C++
 * Calls from C++ to Rust, and Rust types (in the top part)
 * Calls from Rust to C++, and C++ types (in the bottom part)
-* If the function definitions in C++ or Rust don't match the cxx::bridge,
-  a compilation failure results.
 
-**Common misconception**: It _looks_ like a C++ header is being parser by Rust,
+**Common misconception**: It _looks_ like a C++ header is being parsed by Rust,
 but this is misleading. This header is never interpreted by Rust, but simply
 `#include`d in the generated C++ code for the benefit of C++ compilers.
-</details>
\ No newline at end of file
+
+</details>