docs: improve language in Android section (#2890)

I asked Gemini to review the English for inconsistencies and grammar
mistakes. This is the result and I hope it's useful!

As a non-native speaker, it is hard for me to evaluate the finer
details, so let me know if you would like to see changes (or even
better: make them directly in the PR with the suggestion function).

---------

Co-authored-by: Dmitri Gribenko <gribozavr@gmail.com>

src/android/aidl.md

@@ -1,18 +1,16 @@
 # AIDL
 
-The
-[Android Interface Definition Language
-(AIDL)](https://developer.android.com/guide/components/aidl) is supported in
-Rust:
+Rust supports the
+[Android Interface Definition Language (AIDL)](https://developer.android.com/guide/components/aidl):
 
-- Rust code can call existing AIDL servers,
+- Rust code can call existing AIDL servers.
 - You can create new AIDL servers in Rust.
 
 <details>
 
-- AIDL is what enables Android apps to interact with each other.
+- AIDL enables Android apps to interact with each other.
 
-- Since Rust is supported as a first-class citizen in this ecosystem, Rust
-  services can be called by any other process on the phone.
+- Since Rust is a first-class citizen in this ecosystem, other processes on the
+  device can call Rust services.
 
 </details>

src/android/aidl/birthday-service.md

@@ -1,5 +1,4 @@
 # Birthday Service Tutorial
 
-To illustrate how to use Rust with Binder, we're going to walk through the
-process of creating a Binder interface. We're then going to both implement the
-described service and write client code that talks to that service.
+To illustrate using Rust with Binder, we will create a Binder interface. Then,
+we'll implement the service and write a client that talks to it.

src/android/aidl/example-service/changing-definition.md

@@ -1,7 +1,7 @@
 # Changing API
 
-Let us extend the API with more functionality: we want to let clients specify a
-list of lines for the birthday card:
+Let's extend the API: we'll let clients specify a list of lines for the birthday
+card:
 
 ```java
 package com.example.birthdayservice;

src/android/aidl/example-service/server.md

@@ -16,21 +16,21 @@ _birthday_service/Android.bp_:
 
 <details>
 
-The process for taking a user-defined service implementation (in this case the
+The process for taking a user-defined service implementation (in this case, the
 `BirthdayService` type, which implements the `IBirthdayService`) and starting it
-as a Binder service has multiple steps, and may appear more complicated than
+as a Binder service has multiple steps. This may appear more complicated than
 students are used to if they've used Binder from C++ or another language.
 Explain to students why each step is necessary.
 
 1. Create an instance of your service type (`BirthdayService`).
-1. Wrap the service object in corresponding `Bn*` type (`BnBirthdayService` in
-   this case). This type is generated by Binder and provides the common Binder
-   functionality that would be provided by the `BnBinder` base class in C++. We
-   don't have inheritance in Rust, so instead we use composition, putting our
-   `BirthdayService` within the generated `BnBinderService`.
-1. Call `add_service`, giving it a service identifier and your service object
+2. Wrap the service object in the corresponding `Bn*` type (`BnBirthdayService`
+   in this case). This type is generated by Binder and provides common Binder
+   functionality, similar to the `BnBinder` base class in C++. Since Rust
+   doesn't have inheritance, we use composition, putting our `BirthdayService`
+   within the generated `BnBinderService`.
+3. Call `add_service`, giving it a service identifier and your service object
    (the `BnBirthdayService` object in the example).
-1. Call `join_thread_pool` to add the current thread to Binder's thread pool and
+4. Call `join_thread_pool` to add the current thread to Binder's thread pool and
    start listening for connections.
 
 </details>

src/android/aidl/example-service/service-bindings.md

@@ -25,7 +25,7 @@ trait to talk to the service.
 <details>
 
 - Point out how the generated function signature, specifically the argument and
-  return types, correspond the interface definition.
+  return types, correspond to the interface definition.
   - `String` for an argument results in a different Rust type than `String` as a
     return type.
 

src/android/aidl/example-service/service.md

@@ -25,7 +25,7 @@ _birthday_service/Android.bp_:
   each of the segments is necessary.
 - Note that `wishHappyBirthday` and other AIDL IPC methods take `&self` (instead
   of `&mut self`).
-  - This is necessary because binder responds to incoming requests on a thread
+  - This is necessary because Binder responds to incoming requests on a thread
     pool, allowing for multiple requests to be processed in parallel. This
     requires that the service methods only get a shared reference to `self`.
   - Any state that needs to be modified by the service will have to be put in
@@ -33,6 +33,6 @@ _birthday_service/Android.bp_:
   - The correct approach for managing service state depends heavily on the
     details of your service.
 - TODO: What does the `binder::Interface` trait do? Are there methods to
-  override? Where source?
+  override? Where is the source?
 
 </details>

src/android/aidl/types/arrays.md

@@ -1,6 +1,6 @@
 # Array Types
 
-The array types (`T[]`, `byte[]`, and `List<T>`) get translated to the
+The array types (`T[]`, `byte[]`, and `List<T>`) are translated to the
 appropriate Rust array type depending on how they are used in the function
 signature:
 

src/android/build-rules.md

@@ -1,6 +1,6 @@
 # Build Rules
 
-The Android build system (Soong) supports Rust via a number of modules:
+The Android build system (Soong) supports Rust through several modules:
 
 | Module Type       | Description                                                                                        |
 | ----------------- | -------------------------------------------------------------------------------------------------- |
@@ -17,13 +17,13 @@ We will look at `rust_binary` and `rust_library` next.
 
 <details>
 
-Additional items speaker may mention:
+Additional items the speaker may mention:
 
-- Cargo is not optimized for multi-language repos, and also downloads packages
-  from the internet.
+- Cargo is not optimized for multi-language repositories, and also downloads
+  packages from the internet.
 
 - For compliance and performance, Android must have crates in-tree. It must also
-  interop with C/C++/Java code. Soong fills that gap.
+  interoperate with C/C++/Java code. Soong fills that gap.
 
 - Soong has many similarities to [Bazel](https://bazel.build/), which is the
   open-source variant of Blaze (used in google3).

src/android/build-rules/binary.md

@@ -1,6 +1,6 @@
 # Rust Binaries
 
-Let us start with a simple application. At the root of an AOSP checkout, create
+Let's start with a simple application. At the root of an AOSP checkout, create
 the following files:
 
 _hello_rust/Android.bp_:
@@ -33,7 +33,7 @@ Hello from Rust!
   that all modules have documentation. Try removing it and see what error you
   get.
 
-- Stress that the Rust build rules look like the other Soong rules. This is on
-  purpose to make it as easy to use Rust as C++ or Java.
+- Stress that the Rust build rules look like the other Soong rules. This is by
+  design, to make using Rust as easy as C++ or Java.
 
 </details>

src/android/interoperability.md

@@ -6,8 +6,8 @@ that you can:
 - Call Rust functions from other languages.
 - Call functions written in other languages from Rust.
 
-When you call functions in a foreign language we say that you're using a
-_foreign function interface_, also known as FFI.
+When you call functions in a foreign language, you're using a _foreign function
+interface_, also known as FFI.
 
 <details>
 

src/android/interoperability/cpp.md

@@ -1,7 +1,6 @@
 # With C++
 
-The [CXX crate][1] makes it possible to do safe interoperability between Rust
-and C++.
+The [CXX crate][1] enables safe interoperability between Rust and C++.
 
 The overall approach looks like this:
 

src/android/interoperability/with-c.md

@@ -30,9 +30,9 @@ We will look at better options next.
 - The [`"C"` part][extern-abi] of the `extern` block tells Rust that `abs` can
   be called using the C [ABI] (application binary interface).
 
-- The `safe fn abs` part tells that Rust that `abs` is a safe function. By
-  default, extern functions are considered unsafe, but since `abs(x)` is valid
-  for any `x`, we can declare it safe.
+- The `safe fn abs` part tells Rust that `abs` is a safe function. By default,
+  extern functions are unsafe, but since `abs(x)` can't trigger undefined
+  behavior with any `x`, we can declare it safe.
 
 </details>