Build-test (documentation) on the host and fix broken doc samples

.github/workflows/ci.yml

@@ -96,6 +96,11 @@ jobs:
         run: >
           cargo ndk -t arm64-v8a doc --no-deps
 
+      - name: Tests (host build-testing)
+        run: |
+          cargo test -F native-activity -F test
+          cargo test -F game-activity -F test
+
   format:
     runs-on: ubuntu-latest
     steps:

android-activity/Cargo.toml

@@ -30,6 +30,10 @@ native-activity = []
 api-level-30 = ["ndk/api-level-30"]
 api-level-33 = ["api-level-30", "ndk/api-level-33"]
 
+# "Internal" feature to allow build-testing this crate for the host
+# architecture, needed to make doctests actually compile sample code.
+test = ["ndk/test", "ndk-sys/test"]
+
 [dependencies]
 log = "0.4"
 jni-sys = "0.3"

android-activity/src/input/sdk.rs

@@ -284,13 +284,12 @@ impl KeyCharacterMap {
 
     /// Get the character that is produced by combining the dead key producing accent with the key producing character c.
     ///
-    /// For example, ```get_dead_char('`', 'e')``` returns 'è'. `get_dead_char('^', ' ')` returns '^' and `get_dead_char('^', '^')` returns '^'.
+    /// For example, ``get_dead_char('`', 'e')`` returns `'è'`. `get_dead_char('^', ' ')` returns `'^'` and `get_dead_char('^', '^')` returns `'^'`.
     ///
     /// # Errors
     ///
-    /// Since this API needs to use JNI internally to call into the Android JVM it may return
-    /// a [`AppError::JavaError`] in case there is a spurious JNI error or an exception
-    /// is caught.
+    /// Since this API needs to use JNI internally to call into the Android JVM it may return a
+    /// [`AppError::JavaError`] in case there is a spurious JNI error or an exception is caught.
     pub fn get_dead_char(
         &self,
         accent_char: char,

android-activity/src/lib.rs

@@ -13,15 +13,15 @@
 //!    a wider range of devices.
 //!
 //! Standalone applications based on this crate need to be built as `cdylib` libraries, like:
-//! ```
+//! ```toml
 //! [lib]
 //! crate_type=["cdylib"]
 //! ```
 //!
 //! and implement a `#[no_mangle]` `android_main` entry point like this:
-//! ```rust
+//! ```
 //! #[no_mangle]
-//! fn android_main(app: AndroidApp) {
+//! fn android_main(app: android_activity::AndroidApp) {
 //!
 //! }
 //! ```
@@ -64,6 +64,7 @@
 //! These are undone after `android_main()` returns
 //!
 //! # Android Extensible Enums
+// TODO: Move this to the NDK crate, which now implements this for most of the code?
 //!
 //! There are numerous enums in the `android-activity` API which are effectively
 //! bindings to enums declared in the Android SDK which need to be considered
@@ -95,7 +96,7 @@
 //! For example, here is how you could ensure forwards compatibility with both
 //! compile-time and runtime extensions of a `SomeEnum` enum:
 //!
-//! ```rust
+//! ```ignore
 //! match some_enum {
 //!     SomeEnum::Foo => {},
 //!     SomeEnum::Bar => {},
@@ -126,7 +127,7 @@
 
 use bitflags::bitflags;
 
-#[cfg(not(target_os = "android"))]
+#[cfg(all(not(target_os = "android"), not(feature = "test")))]
 compile_error!("android-activity only supports compiling for Android");
 
 #[cfg(all(feature = "game-activity", feature = "native-activity"))]
@@ -550,10 +551,10 @@
     /// between native Rust code and Java/Kotlin code running within the JVM.
     ///
     /// If you use the [`jni`] crate you can wrap this as a [`JavaVM`] via:
-    /// ```ignore
+    /// ```no_run
     /// # use jni::JavaVM;
-    /// # let app: AndroidApp = todo!();
-    /// let vm = unsafe { JavaVM::from_raw(app.vm_as_ptr()) };
+    /// # let app: android_activity::AndroidApp = todo!();
+    /// let vm = unsafe { JavaVM::from_raw(app.vm_as_ptr().ast()) };
     /// ```
     ///
     /// [`jni`]: https://crates.io/crates/jni
@@ -565,10 +566,10 @@
     /// Returns a JNI object reference for this application's JVM `Activity` as a pointer
     ///
     /// If you use the [`jni`] crate you can wrap this as an object reference via:
-    /// ```ignore
+    /// ```no_run
     /// # use jni::objects::JObject;
-    /// # let app: AndroidApp = todo!();
-    /// let activity = unsafe { JObject::from_raw(app.activity_as_ptr()) };
+    /// # let app: android_activity::AndroidApp = todo!();
+    /// let activity = unsafe { JObject::from_raw(app.activity_as_ptr().cast()) };
     /// ```
     ///
     /// # JNI Safety
@@ -725,16 +726,16 @@
     /// # Example
     /// Code to iterate all pending input events would look something like this:
     ///
-    /// ```rust
+    /// ```
     /// match app.input_events_iter() {
     ///     Ok(mut iter) => {
     ///         loop {
     ///             let read_input = iter.next(|event| {
     ///                 let handled = match event {
     ///                     InputEvent::KeyEvent(key_event) => {
     ///                         // Snip
     ///                     }
     ///                     InputEvent::MotionEvent(motion_event) => {
     ///                         // Snip
     ///                     }
     ///                     event => {
@@ -780,17 +781,17 @@
     ///
     /// Code to handle unicode character mapping as well as combining dead keys could look some thing like:
     ///
-    /// ```rust
+    /// ```
     /// let mut combining_accent = None;
     /// // Snip
     ///
     /// let combined_key_char = if let Ok(map) = app.device_key_character_map(device_id) {
     ///     match map.get(key_event.key_code(), key_event.meta_state()) {
     ///         Ok(KeyMapChar::Unicode(unicode)) => {
     ///             let combined_unicode = if let Some(accent) = combining_accent {
     ///                 match map.get_dead_char(accent, unicode) {
     ///                     Ok(Some(key)) => {
     ///                         info!("KeyEvent: Combined '{unicode}' with accent '{accent}' to give '{key}'");
     ///                         Some(key)
     ///                     }
     ///                     Ok(None) => None,
@@ -800,19 +801,19 @@
     ///                     }
     ///                 }
     ///             } else {
     ///                 info!("KeyEvent: Pressed '{unicode}'");
     ///                 Some(unicode)
     ///             };
     ///             combining_accent = None;
     ///             combined_unicode.map(|unicode| KeyMapChar::Unicode(unicode))
     ///         }
     ///         Ok(KeyMapChar::CombiningAccent(accent)) => {
     ///             info!("KeyEvent: Pressed 'dead key' combining accent '{accent}'");
     ///             combining_accent = Some(accent);
     ///             Some(KeyMapChar::CombiningAccent(accent))
     ///         }
     ///         Ok(KeyMapChar::None) => {
     ///             info!("KeyEvent: Pressed non-unicode key");
     ///             combining_accent = None;
     ///             None
     ///         }