ndk: Move library documentation to modules

Instead of having an outdated overview of modules and their contents in
the library documentation, move this to the module documentation header.
Rustdoc already provides a clickable link for every module (these manual
list didn't include _any_ links), and also includes the first
sentence/paragraph from this module documentation.

This also inserts some missing `struct` documentation and cleans up
existing references to link to the NDK docs more often and specify
exactly what type it is wrapping, instead of linking to the "rather
useless" `ffi` representation for that NDK type.

ndk-glue/src/lib.rs

@@ -23,13 +23,13 @@ pub use ndk_macro::main;
 
 /// `ndk-glue` macros register the reading end of an event pipe with the
 /// main [`ThreadLooper`] under this `ident`.
-/// When returned from [`ThreadLooper::poll_*`](ThreadLooper::poll_once)
+/// When returned from [`ThreadLooper::poll_*`][ThreadLooper::poll_once]
 /// an event can be retrieved from [`poll_events()`].
 pub const NDK_GLUE_LOOPER_EVENT_PIPE_IDENT: i32 = 0;
 
 /// The [`InputQueue`] received from Android is registered with the main
 /// [`ThreadLooper`] under this `ident`.
-/// When returned from [`ThreadLooper::poll_*`](ThreadLooper::poll_once)
+/// When returned from [`ThreadLooper::poll_*`][ThreadLooper::poll_once]
 /// an event can be retrieved from [`input_queue()`].
 pub const NDK_GLUE_LOOPER_INPUT_QUEUE_IDENT: i32 = 1;
 

ndk-sys/src/lib.rs

@@ -1,9 +1,6 @@
 //! Raw FFI bindings to the Android NDK.
 //!
 //! The bindings are pre-generated and the right one for the platform is selected at compile time.
-//!
-//! If you are including `android_native_app_glue.c`, the [`android_native_app_glue`
-//! module](android_native_app_glue/index.html) contains the interface for that.
 
 // Bindgen lints
 #![allow(non_upper_case_globals)]

ndk/CHANGELOG.md

@@ -12,6 +12,7 @@
 - native_activity: Add `set_window_format()` setter. (#277)
 - native_activity: Add `set_window_flags()` to change window behavior. (#278)
 - Add `SurfaceTexture` bindings. (#267)
+- Improve library and structure documentation, linking back to the NDK docs more rigorously. (#290)
 
 # 0.6.0 (2022-01-05)
 

ndk/src/asset.rs

@@ -1,12 +1,16 @@
-//! Assets
+//! Bindings for [`AAsset`], [`AAssetDir`] and [`AAssetManager`]
 //!
-//! See also [the NDK docs](https://developer.android.com/ndk/reference/group/asset)
+//! [`AAsset`]: https://developer.android.com/ndk/reference/group/asset#aasset
+//! [`AAssetDir`]: https://developer.android.com/ndk/reference/group/asset#aassetdir
+//! [`AAssetManager`]: https://developer.android.com/ndk/reference/group/asset#aassetmanager
 
 use std::ffi::{CStr, CString};
 use std::io;
 use std::ptr::NonNull;
 
-/// A native `AAssetManager *`.
+/// A native [`AAssetManager *`]
+///
+/// [`AAssetManager *`]: https://developer.android.com/ndk/reference/group/asset#aassetmanager
 #[derive(Debug)]
 pub struct AssetManager {
     ptr: NonNull<ffi::AAssetManager>,
@@ -55,7 +59,7 @@ impl AssetManager {
     }
 }
 
-/// A native `AAssetDir *`.
+/// A native [`AAssetDir *`]
 ///
 /// ```no_run
 /// # use std::ffi::CString;
@@ -80,6 +84,8 @@ impl AssetManager {
 ///     // ...
 /// }
 /// ```
+///
+/// [`AAssetDir *`]: https://developer.android.com/ndk/reference/group/asset#aassetdir
 #[derive(Debug)]
 pub struct AssetDir {
     ptr: NonNull<ffi::AAssetDir>,
@@ -141,7 +147,7 @@ impl Iterator for AssetDir {
     }
 }
 
-/// A native `AAsset *`, open in the streaming mode
+/// A native [`AAsset *`], opened in streaming mode
 ///
 /// ```no_run
 /// # use std::ffi::CString;
@@ -157,6 +163,8 @@ impl Iterator for AssetDir {
 /// asset.read_to_end(&mut data);
 /// // ... use data ...
 /// ```
+///
+/// [`AAsset *`]: https://developer.android.com/ndk/reference/group/asset#aasset
 #[derive(Debug)]
 pub struct Asset {
     ptr: NonNull<ffi::AAsset>,

ndk/src/audio.rs

@@ -1,7 +1,11 @@
-//! Bindings for the NDK AAudio Android audio API.
+//! Bindings for [`AAudioStream`] and [`AAudioStreamBuilder`]
 //!
-//! See also [the NDK docs](https://developer.android.com/ndk/guides/audio/aaudio/aaudio)
-//! and [the NDK API reference](https://developer.android.com/ndk/reference/group/audio)
+//! See [the NDK guide](https://developer.android.com/ndk/guides/audio/aaudio/aaudio) for
+//! design and usage instructions, and [the NDK reference](https://developer.android.com/ndk/reference/group/audio)
+//! for an API overview.
+//!
+//! [`AAudioStream`]: https://developer.android.com/ndk/reference/group/audio#aaudiostream
+//! [`AAudioStreamBuilder`]: https://developer.android.com/ndk/reference/group/audio#aaudiostreambuilder
 #![cfg(feature = "audio")]
 
 use num_enum::{IntoPrimitive, TryFromPrimitive};
@@ -18,33 +22,40 @@ use thiserror::Error;
 
 /// Specifying if audio may or may not be captured by other apps or the system.
 ///
-/// Note that these match the equivalent values in android.media.AudioAttributes
+/// Note that these match the equivalent values in [`android.media.AudioAttributes`]
 /// in the Android Java API.
+///
+/// [`android.media.AudioAttributes`]: https://developer.android.com/reference/android/media/AudioAttributes
 #[cfg(feature = "api-level-29")]
 #[repr(u32)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)]
 pub enum AudioAllowedCapturePolicy {
     /// Indicates that the audio may be captured by any app.
     ///
-    /// For privacy, the following [usages][AudioUsage] can not be recorded:
-    /// `VoiceCommunication*`, `Notification*`, `Assistance*` and `Assistant`.
+    /// For privacy, the following [usages][AudioUsage] can not be recorded: `VoiceCommunication*`,
+    /// `Notification*`, `Assistance*` and [`Assistant`][AudioUsage::Assistant].
+    ///
+    /// On Android Q, this means only [`Media`][AudioUsage::Media] and [`Game`][AudioUsage::Game] may be captured.
     ///
-    /// On Android Q, this means only `Media` and `Game` may be captured.
+    /// See [`MediaProjection`] and [`AudioStreamBuilder::allowed_capture_policy()`].
     ///
-    /// See android.media.AudioAttributes#ALLOW_CAPTURE_BY_ALL.
+    /// [`MediaProjection`]: https://developer.android.com/reference/android/media/projection/MediaProjection
     AllowCaptureByAll = ffi::AAUDIO_ALLOW_CAPTURE_BY_ALL,
     /// Indicates that the audio may only be captured by system apps.
     ///
-    /// System apps can capture for many purposes like accessibility, user guidance...
-    /// but have strong restriction. See
-    /// android.media.AudioAttributes#ALLOW_CAPTURE_BY_SYSTEM for what the system apps
-    /// can do with the capture audio.
+    /// System apps can capture for many purposes like accessibility, live captions, user
+    /// guidance... but abide to the following restrictions:
+    /// - the audio cannot leave the device;
+    /// - the audio cannot be passed to a third party app;
+    /// - the audio cannot be recorded at a higher quality than 16kHz 16bit mono.
+    ///
+    /// See [`AudioStreamBuilder::allowed_capture_policy()`].
     AllowCaptureBySystem = ffi::AAUDIO_ALLOW_CAPTURE_BY_SYSTEM,
     /// Indicates that the audio may not be recorded by any app, even if it is a system app.
     ///
-    /// It is encouraged to use `AllowCaptureBySystem` instead of this value as system apps
-    /// provide significant and useful features for the user (eg. accessibility).
-    /// See android.media.AudioAttributes#ALLOW_CAPTURE_BY_NONE.
+    /// It is encouraged to use [`AllowCaptureBySystem`][Self::AllowCaptureBySystem] instead of
+    /// this value as system apps provide significant and useful features for the user (such as
+    /// live captioning and accessibility).
     AllowCaptureByNone = ffi::AAUDIO_ALLOW_CAPTURE_BY_NONE,
 }
 
@@ -55,8 +66,10 @@ pub enum AudioAllowedCapturePolicy {
 /// an audio book application) this information might be used by the audio framework to
 /// enforce audio focus.
 ///
-/// Note that these match the equivalent values in android.media.AudioAttributes
+/// Note that these match the equivalent values in [`android.media.AudioAttributes`]
 /// in the Android Java API.
+///
+/// [`android.media.AudioAttributes`]: https://developer.android.com/reference/android/media/AudioAttributes
 #[cfg(feature = "api-level-28")]
 #[repr(u32)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)]
@@ -157,8 +170,10 @@ pub enum AudioSharingMode {
 /// This information is used by certain platforms or routing policies
 /// to make more refined volume or routing decisions.
 ///
-/// Note that these match the equivalent values in android.media.AudioAttributes
+/// Note that these match the equivalent values in [`android.media.AudioAttributes`]
 /// in the Android Java API.
+///
+/// [`android.media.AudioAttributes`]: https://developer.android.com/reference/android/media/AudioAttributes
 #[cfg(feature = "api-level-28")]
 #[repr(u32)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)]
@@ -372,6 +387,9 @@ fn enum_return_value<T: TryFrom<u32>>(return_value: i32) -> Result<T> {
         .ok_or(AudioError::UnsupportedValue(return_value))
 }
 
+/// A native [`AAudioStreamBuilder *`]
+///
+/// [`AAudioStreamBuilder *`]: https://developer.android.com/ndk/reference/group/audio#aaudiostreambuilder
 pub struct AudioStreamBuilder {
     inner: NonNull<ffi::AAudioStreamBuilder>,
     data_callback: Option<AudioStreamDataCallback>,
@@ -429,13 +447,15 @@ impl AudioStreamBuilder {
     /// The default is [`AudioAllowedCapturePolicy::AllowCaptureByAll`].
     ///
     /// Note that an application can also set its global policy, in which case the most restrictive
-    /// policy is always applied. See android.media.AudioAttributes#setAllowedCapturePolicy(int)
+    /// policy is always applied. See [`android.media.AudioAttributes#setAllowedCapturePolicy(int)`].
     ///
     /// Available since API level 29.
     ///
     /// # Arguments
     ///
     /// * `policy` - the desired level of opt-out from being captured.
+    ///
+    /// [`android.media.AudioAttributes#setAllowedCapturePolicy(int)`]: https://developer.android.com/reference/android/media/AudioAttributes.Builder#setAllowedCapturePolicy(int)
     #[cfg(feature = "api-level-29")]
     pub fn allowed_capture_policy(self, capture_policy: AudioAllowedCapturePolicy) -> Self {
         unsafe {
@@ -881,6 +901,9 @@ impl Drop for AudioStreamBuilder {
     }
 }
 
+/// A native [`AAudioStream *`]
+///
+/// [`AAudioStream *`]: https://developer.android.com/ndk/reference/group/audio#aaudiostream
 pub struct AudioStream {
     inner: NonNull<ffi::AAudioStream>,
     data_callback: Option<AudioStreamDataCallback>,
@@ -1303,11 +1326,11 @@ impl AudioStream {
     /// Returns the number of frames actually written or a negative error.
     ///
     /// The call will wait until the write is complete or until it runs out of time.
-    /// If timeoutNanos is zero then this call will not wait.
+    /// If `timeout_nanoseconds` is zero then this call will not wait.
     ///
-    /// Note that timeoutNanoseconds is a relative duration in wall clock time.
+    /// Note that `timeout_nanoseconds` is a relative duration in wall clock time.
     /// Time will not stop if the thread is asleep.
-    /// So it will be implemented using CLOCK_BOOTTIME.
+    /// So it will be implemented using `CLOCK_BOOTTIME`.
     ///
     /// This call is "strong non-blocking" unless it has to wait for room in the buffer.
     ///

ndk/src/bitmap.rs

@@ -1,3 +1,9 @@
+//! Bindings for [`AndroidBitmap`] functions
+//!
+//! These functions operate directly on a JNI [`android.graphics.Bitmap`] instance.
+//!
+//! [`AndroidBitmap`]: https://developer.android.com/ndk/reference/group/bitmap
+//! [`android.graphics.Bitmap`]: https://developer.android.com/reference/android/graphics/Bitmap
 #![cfg(feature = "bitmap")]
 
 use jni_sys::{jobject, JNIEnv};
@@ -58,17 +64,23 @@ mod temp_allow_deprecated {
 }
 pub use temp_allow_deprecated::*;
 
+/// An immediate wrapper over [`android.graphics.Bitmap`]
+///
+/// [`android.graphics.Bitmap`]: https://developer.android.com/reference/android/graphics/Bitmap
 #[derive(Debug)]
 pub struct AndroidBitmap {
     env: *mut JNIEnv,
     inner: jobject,
 }
 
 impl AndroidBitmap {
-    /// Create an [`AndroidBitmap`] from JNI pointers
+    /// Create an [`AndroidBitmap`] wrapper from JNI pointers
     ///
     /// # Safety
-    /// By calling this function, you assert that these are valid pointers to JNI objects.
+    /// This function should be called with a healthy JVM pointer and with a non-null
+    /// [`android.graphics.Bitmap`], which must be kept alive on the Java/Kotlin side.
+    ///
+    /// [`android.graphics.Bitmap`]: https://developer.android.com/reference/android/graphics/Bitmap
     pub unsafe fn from_jni(env: *mut JNIEnv, bitmap: jobject) -> Self {
         Self { env, inner: bitmap }
     }
@@ -104,6 +116,9 @@ impl AndroidBitmap {
     }
 }
 
+/// A native [`AndroidBitmapInfo`]
+///
+/// [`AndroidBitmapInfo`]: https://developer.android.com/ndk/reference/struct/android-bitmap-info#struct_android_bitmap_info
 #[derive(Copy, Clone, Debug)]
 pub struct AndroidBitmapInfo {
     inner: ffi::AndroidBitmapInfo,

ndk/src/configuration.rs

@@ -1,22 +1,25 @@
-//! Bindings for `AConfiguration`.
+//! Bindings for [`AConfiguration`]
 //!
 //! See also the [NDK docs](https://developer.android.com/ndk/reference/group/configuration) for
-//! `AConfiguration`, as well as the [docs for providing
+//! [`AConfiguration`], as well as the [docs for providing
 //! resources](https://developer.android.com/guide/topics/resources/providing-resources.html),
 //! which explain many of the configuration values.  The [`android.content.res.Configuration`
 //! javadoc](https://developer.android.com/reference/android/content/res/Configuration.html) may
 //! also have useful information.
+//!
+//! [`AConfiguration`]: https://developer.android.com/ndk/reference/group/configuration#aconfiguration
 
 use crate::asset::AssetManager;
 use num_enum::{IntoPrimitive, TryFromPrimitive};
 use std::convert::TryInto;
 use std::fmt;
 use std::ptr::NonNull;
 
-/// A native `AConfiguration *`.
+/// A native [`AConfiguration *`]
+///
+/// [`Configuration`] is an opaque type used to get and set various subsystem configurations.
 ///
-/// This stores information about configuration.  See [the NDK
-/// docs](https://developer.android.com/ndk/reference/group/configuration)
+/// [`AConfiguration *`]: https://developer.android.com/ndk/reference/group/configuration#aconfiguration
 pub struct Configuration {
     ptr: NonNull<ffi::AConfiguration>,
 }
@@ -325,7 +328,7 @@ impl Configuration {
     }
 }
 
-/// A bitfield representing the differences between two `Configuration`s
+/// A bitfield representing the differences between two [`Configuration`]s
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub struct DiffResult(pub u32);