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,8 +22,10 @@ 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)]
@@ -372,6 +378,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>,
@@ -881,6 +890,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 +1315,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);
 

ndk/src/event.rs

@@ -1,19 +1,22 @@
-//! A wrapper around the NDK's `AInputEvent`.
+//! Bindings for [`AInputEvent`, `AKeyEvent` and `AMotionEvent`]
 //!
-//! Most of these operations directly wrap functions in the NDK.  Documentation for all NDK
-//! functions in this module can be found
-//! [here](https://developer.android.com/ndk/reference/group/input).  See also the javadocs for
-//! [`android.view.InputEvent`](https://developer.android.com/reference/android/view/InputEvent.html),
-//! [`android.view.MotionEvent`](https://developer.android.com/reference/android/view/MotionEvent.html),
-//! and [`android.view.KeyEvent`](https://developer.android.com/reference/android/view/KeyEvent).
+//! Most of these operations directly wrap functions in the NDK.
+//!
+//! See also the Java docs for [`android.view.InputEvent`], [`android.view.MotionEvent`], and
+//! [`android.view.KeyEvent`].
+//!
+//! [`AInputEvent`, `AKeyEvent` and `AMotionEvent`]: https://developer.android.com/ndk/reference/group/input
+//! [`android.view.InputEvent`]: https://developer.android.com/reference/android/view/InputEvent.html
+//! [`android.view.MotionEvent`]: https://developer.android.com/reference/android/view/MotionEvent.html
+//! [`android.view.KeyEvent`]: https://developer.android.com/reference/android/view/KeyEvent
 
 use num_enum::{IntoPrimitive, TryFromPrimitive};
 use std::convert::TryInto;
 use std::ptr::NonNull;
 
-/// A [`*const AInputEvent`](ffi::AInputEvent)
+/// A native [`AInputEvent *`]
 ///
-/// See [the NDK docs](https://developer.android.com/ndk/reference/group/input#ainputevent)
+/// [`AInputEvent *`]: https://developer.android.com/ndk/reference/group/input#ainputevent
 #[derive(Debug)]
 pub enum InputEvent {
     MotionEvent(MotionEvent),
@@ -43,7 +46,7 @@ pub enum Source {
     Any = ffi::AINPUT_SOURCE_ANY,
 }
 
-/// An enum representing the class of an [`InputEvent`] source
+/// An enum representing the class of an [`InputEvent`] source.
 ///
 /// See [the NDK docs](https://developer.android.com/ndk/reference/group/input#anonymous-enum-35)
 #[derive(Debug, Clone, Copy, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)]
@@ -62,7 +65,7 @@ impl InputEvent {
     ///
     /// # Safety
     /// By calling this function, you assert that the pointer is a valid pointer to a
-    /// native [`AInputEvent`](ffi::AInputEvent).
+    /// native [`ffi::AInputEvent`].
     #[inline]
     pub unsafe fn from_ptr(ptr: NonNull<ffi::AInputEvent>) -> Self {
         match ffi::AInputEvent_getType(ptr.as_ptr()) as u32 {
@@ -72,7 +75,7 @@ impl InputEvent {
         }
     }
 
-    /// Returns a pointer to the native [`AInputEvent`](ffi::AInputEvent).
+    /// Returns a pointer to the native [`ffi::AInputEvent`].
     #[inline]
     pub fn ptr(&self) -> NonNull<ffi::AInputEvent> {
         match self {
@@ -178,10 +181,14 @@ impl MetaState {
     }
 }
 
-/// A motion event.
+/// A motion event
+///
+/// Wraps an [`AInputEvent *`] of the [`ffi::AINPUT_EVENT_TYPE_MOTION`] type.
 ///
 /// For general discussion of motion events in Android, see [the relevant
 /// javadoc](https://developer.android.com/reference/android/view/MotionEvent).
+///
+/// [`AInputEvent *`]: https://developer.android.com/ndk/reference/group/input#ainputevent
 #[derive(Clone, Debug)]
 pub struct MotionEvent {
     ptr: NonNull<ffi::AInputEvent>,
@@ -340,18 +347,18 @@ impl MotionEventFlags {
 }
 
 impl MotionEvent {
-    /// Constructs a MotionEvent from a pointer to a native [`AInputEvent`](ffi::AInputEvent)
+    /// Constructs a MotionEvent from a pointer to a native [`ffi::AInputEvent`]
     ///
     /// # Safety
     /// By calling this method, you assert that the pointer is a valid, non-null pointer to a
-    /// native [`AInputEvent`](ffi::AInputEvent) and that that [`AInputEvent`](ffi::AInputEvent)
+    /// native [`ffi::AInputEvent`] and that [`ffi::AInputEvent`]
     /// is an `AMotionEvent`.
     #[inline]
     pub unsafe fn from_ptr(ptr: NonNull<ffi::AInputEvent>) -> Self {
         Self { ptr }
     }
 
-    /// Returns a pointer to the native [`AInputEvent`](ffi::AInputEvent)
+    /// Returns a pointer to the native [`ffi::AInputEvent`]
     #[inline]
     pub fn ptr(&self) -> NonNull<ffi::AInputEvent> {
         self.ptr
@@ -393,9 +400,9 @@ impl MotionEvent {
     /// Pointer indices can change per motion event.  For an identifier that stays the same, see
     /// [`Pointer::pointer_id()`].
     ///
-    /// This only has a meaning when the [action](Self::action) is one of [`Up`](MotionAction::Up),
-    /// [`Down`](MotionAction::Down), [`PointerUp`](MotionAction::PointerUp),
-    /// or [`PointerDown`](MotionAction::PointerDown).
+    /// This only has a meaning when the [action][Self::action] is one of [`Up`][MotionAction::Up],
+    /// [`Down`][MotionAction::Down], [`PointerUp`][MotionAction::PointerUp],
+    /// or [`PointerDown`][MotionAction::PointerDown].
     #[inline]
     pub fn pointer_index(&self) -> usize {
         let action = unsafe { ffi::AMotionEvent_getAction(self.ptr.as_ptr()) as u32 };
@@ -438,7 +445,7 @@ impl MotionEvent {
 
     /// The pointer at a given pointer index. Panics if the pointer index is out of bounds.
     ///
-    /// If you need to loop over all the pointers, prefer the [`pointers()`](Self::pointers) method.
+    /// If you need to loop over all the pointers, prefer the [`pointers()`][Self::pointers] method.
     #[inline]
     pub fn pointer_at_index(&self, index: usize) -> Pointer<'_> {
         if index >= self.pointer_count() {
@@ -994,10 +1001,14 @@ impl ExactSizeIterator for HistoricalPointersIter<'_> {
     }
 }
 
-/// A key event.
+/// A key event
+///
+/// Wraps an [`AInputEvent *`] of the [`ffi::AINPUT_EVENT_TYPE_KEY`] type.
 ///
 /// For general discussion of key events in Android, see [the relevant
 /// javadoc](https://developer.android.com/reference/android/view/KeyEvent).
+///
+/// [`AInputEvent *`]: https://developer.android.com/ndk/reference/group/input#ainputevent
 #[derive(Debug)]
 pub struct KeyEvent {
     ptr: NonNull<ffi::AInputEvent>,
@@ -1314,17 +1325,17 @@ pub enum Keycode {
 }
 
 impl KeyEvent {
-    /// Constructs a KeyEvent from a pointer to a native [`AInputEvent`](ffi::AInputEvent)
+    /// Constructs a KeyEvent from a pointer to a native [`ffi::AInputEvent`]
     ///
     /// # Safety
     /// By calling this method, you assert that the pointer is a valid, non-null pointer to an
-    /// [`AInputEvent`](ffi::AInputEvent), and that that [`AInputEvent`](ffi::AInputEvent) is an `AKeyEvent`.
+    /// [`ffi::AInputEvent`], and that [`ffi::AInputEvent`] is an `AKeyEvent`.
     #[inline]
     pub unsafe fn from_ptr(ptr: NonNull<ffi::AInputEvent>) -> Self {
         Self { ptr }
     }
 
-    /// Returns a pointer to the native [`AInputEvent`](ffi::AInputEvent)
+    /// Returns a pointer to the native [`ffi::AInputEvent`]
     #[inline]
     pub fn ptr(&self) -> NonNull<ffi::AInputEvent> {
         self.ptr