diff --git a/ndk-glue/src/lib.rs b/ndk-glue/src/lib.rs index 65678e9c..4c89d51e 100644 --- a/ndk-glue/src/lib.rs +++ b/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; diff --git a/ndk-sys/src/lib.rs b/ndk-sys/src/lib.rs index 9ad19dc4..5adcb0ca 100644 --- a/ndk-sys/src/lib.rs +++ b/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)] diff --git a/ndk/CHANGELOG.md b/ndk/CHANGELOG.md index 5f4e9693..92c66af4 100644 --- a/ndk/CHANGELOG.md +++ b/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) diff --git a/ndk/src/asset.rs b/ndk/src/asset.rs index 47956502..da772827 100644 --- a/ndk/src/asset.rs +++ b/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, @@ -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, @@ -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, diff --git a/ndk/src/audio.rs b/ndk/src/audio.rs index 7969bdf3..6d3d7a52 100644 --- a/ndk/src/audio.rs +++ b/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>(return_value: i32) -> Result { .ok_or(AudioError::UnsupportedValue(return_value)) } +/// A native [`AAudioStreamBuilder *`] +/// +/// [`AAudioStreamBuilder *`]: https://developer.android.com/ndk/reference/group/audio#aaudiostreambuilder pub struct AudioStreamBuilder { inner: NonNull, data_callback: Option, @@ -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, data_callback: Option, @@ -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. /// diff --git a/ndk/src/bitmap.rs b/ndk/src/bitmap.rs index 5806f63e..b2de892b 100644 --- a/ndk/src/bitmap.rs +++ b/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,6 +64,9 @@ 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, @@ -65,10 +74,13 @@ pub struct AndroidBitmap { } 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, diff --git a/ndk/src/configuration.rs b/ndk/src/configuration.rs index ae020d6d..226b9f1a 100644 --- a/ndk/src/configuration.rs +++ b/ndk/src/configuration.rs @@ -1,11 +1,13 @@ -//! 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}; @@ -13,10 +15,11 @@ 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, } @@ -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); diff --git a/ndk/src/event.rs b/ndk/src/event.rs index 9186db2d..0e74f34b 100644 --- a/ndk/src/event.rs +++ b/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) -> 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 { 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, @@ -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) -> 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 { 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, @@ -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) -> 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 { self.ptr diff --git a/ndk/src/hardware_buffer.rs b/ndk/src/hardware_buffer.rs index c68aa69a..b5b5c2b6 100644 --- a/ndk/src/hardware_buffer.rs +++ b/ndk/src/hardware_buffer.rs @@ -1,3 +1,7 @@ +//! Bindings for [`AHardwareBuffer`] +//! +//! [`AHardwareBuffer`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer + #![cfg(feature = "hardware_buffer")] pub use super::hardware_buffer_format::HardwareBufferFormat; @@ -97,6 +101,9 @@ fn construct(with_ptr: impl FnOnce(*mut T) -> i32) -> Result, @@ -131,7 +138,7 @@ impl HardwareBuffer { } } - /// Create a `HardwareBuffer` from JNI pointers + /// Create a [`HardwareBuffer`] from JNI pointers /// /// # Safety /// By calling this function, you assert that it these are valid pointers to JNI objects. @@ -257,7 +264,7 @@ impl HardwareBuffer { } /// Returns a fence file descriptor that will become signalled when unlocking is completed, - /// or `None` if unlocking is already finished. + /// or [`None`] if unlocking is already finished. pub fn unlock_async(&self) -> Result> { let fence = construct(|res| unsafe { ffi::AHardwareBuffer_unlock(self.as_ptr(), res) })?; Ok(match fence { @@ -296,8 +303,8 @@ impl HardwareBuffer { } } -/// A `HardwareBuffer` with an owned reference, the reference is released when dropped. -/// It behaves much like a strong `Rc` reference. +/// A [`HardwareBuffer`] with an owned reference, the reference is released when dropped. +/// It behaves much like a strong [`std::rc::Rc`] reference. #[derive(Debug)] pub struct HardwareBufferRef { inner: HardwareBuffer, diff --git a/ndk/src/hardware_buffer_format.rs b/ndk/src/hardware_buffer_format.rs index 9d6501d8..e422efed 100644 --- a/ndk/src/hardware_buffer_format.rs +++ b/ndk/src/hardware_buffer_format.rs @@ -1,3 +1,6 @@ +//! Bindings for [`AHardwareBuffer_Format`] +//! +//! [`AHardwareBuffer_Format`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer_format use num_enum::{IntoPrimitive, TryFromPrimitive}; #[repr(u32)] diff --git a/ndk/src/input_queue.rs b/ndk/src/input_queue.rs index 586cd8bc..e7cf73d1 100644 --- a/ndk/src/input_queue.rs +++ b/ndk/src/input_queue.rs @@ -1,4 +1,6 @@ -// TODO: mod docs +//! Bindings for [`AInputQueue`] +//! +//! [`AInputQueue`]: https://developer.android.com/ndk/reference/group/input#ainputqueue use std::os::raw::c_int; use std::ptr; @@ -7,13 +9,17 @@ use std::ptr::NonNull; use crate::event::InputEvent; use crate::looper::ForeignLooper; -// TODO docs +/// A native [`AInputQueue *`] +/// +/// An input queue is the facility through which you retrieve input events. +/// +/// [`AInputQueue *`]: https://developer.android.com/ndk/reference/group/input#ainputqueue #[derive(Debug)] pub struct InputQueue { ptr: NonNull, } -// It gets shared between threads in android_native_app_glue +// It gets shared between threads in `ndk-glue` unsafe impl Send for InputQueue {} unsafe impl Sync for InputQueue {} @@ -21,10 +27,10 @@ unsafe impl Sync for InputQueue {} pub struct InputQueueError; impl InputQueue { - /// Construct an `InputQueue` from the native pointer. + /// Construct an [`InputQueue`] from the native pointer. /// /// # Safety - /// By calling this function, you assert that the pointer is a valid pointer to an NDK `AInputQueue`. + /// By calling this function, you assert that the pointer is a valid pointer to an NDK [`ffi::AInputQueue`]. pub unsafe fn from_ptr(ptr: NonNull) -> Self { Self { ptr } } @@ -68,7 +74,7 @@ impl InputQueue { pub fn finish_event(&self, event: InputEvent, handled: bool) { unsafe { - ffi::AInputQueue_finishEvent(self.ptr.as_ptr(), event.ptr().as_ptr(), handled as c_int); + ffi::AInputQueue_finishEvent(self.ptr.as_ptr(), event.ptr().as_ptr(), handled as c_int) } } @@ -80,13 +86,11 @@ impl InputQueue { id, None, std::ptr::null_mut(), - ); + ) } } pub fn detach_looper(&self) { - unsafe { - ffi::AInputQueue_detachLooper(self.ptr.as_ptr()); - } + unsafe { ffi::AInputQueue_detachLooper(self.ptr.as_ptr()) } } } diff --git a/ndk/src/lib.rs b/ndk/src/lib.rs index 29f267ea..df46eadb 100644 --- a/ndk/src/lib.rs +++ b/ndk/src/lib.rs @@ -1,18 +1,8 @@ //! # Android NDK //! -//! Bindings to the Android NDK. +//! Bindings to the [Android NDK]. //! -//! Currently has bindings: -//! * `InputEvent`, `KeyEvent`, and `MotionEvent`, in the `event` module -//! * `Looper`, in the `looper` module -//! * `InputQueue`, in the `input_queue` module -//! * `AssetManager`, `AssetDir`, and `Asset`, in the `asset` module -//! * `NativeActivity`, in the `native_activity` module -//! * `Configuration`, in the `configuration` module -#![cfg_attr( - feature = "native_app_glue", - doc = " * `native_app_glue`'s `AndroidApp`, in the `android_app` module" -)] +//! [Android NDK]: https://developer.android.com/ndk/reference #![warn(missing_debug_implementations, trivial_casts)] pub mod asset; diff --git a/ndk/src/looper.rs b/ndk/src/looper.rs index 000c106d..4bc27a60 100644 --- a/ndk/src/looper.rs +++ b/ndk/src/looper.rs @@ -1,11 +1,13 @@ -//! Bindings for `ALooper` +//! Bindings for [`ALooper`] //! -//! In Android, `ALooper`s are inherently thread-local. Due to this, there are two different -//! `ALooper` interfaces exposed in this module: +//! In Android, [`ALooper`]s are inherently thread-local. Due to this, there are two different +//! [`ALooper`] interfaces exposed in this module: //! -//! * [`ThreadLooper`], which has methods for the operations performable with a looper in one's own -//! thread; and -//! * [`ForeignLooper`], which has methods for the operations performable with any thread's looper. +//! * [`ThreadLooper`], which has methods for the operations performable with a looper in one's own +//! thread; and +//! * [`ForeignLooper`], which has methods for the operations performable with any thread's looper. +//! +//! [`ALooper`]: https://developer.android.com/ndk/reference/group/looper#alooper use bitflags::bitflags; use std::convert::TryInto; @@ -17,8 +19,10 @@ use std::ptr::NonNull; use std::time::Duration; use thiserror::Error; -/// A thread-local `ALooper`. This contains a native `ALooper *` and promises that there is a +/// A thread-local native [`ALooper *`]. This contains a native `ALooper *` and promises that there is a /// looper associated with the current thread. +/// +/// [`ALooper *`]: https://developer.android.com/ndk/reference/group/looper#alooper #[derive(Debug)] pub struct ThreadLooper { _marker: std::marker::PhantomData<*mut ()>, // Not send or sync @@ -174,7 +178,9 @@ impl ThreadLooper { } } -/// An `ALooper`, not necessarily allocated with the current thread. +/// A native [`ALooper *`], not necessarily allocated with the current thread. +/// +/// [`ALooper *`]: https://developer.android.com/ndk/reference/group/looper#alooper #[derive(Debug)] pub struct ForeignLooper { ptr: NonNull, @@ -209,7 +215,7 @@ impl ForeignLooper { /// /// # Safety /// By calling this function, you guarantee that the pointer is a valid, non-null pointer to an - /// NDK `ALooper`. + /// NDK [`ffi::ALooper`]. #[inline] pub unsafe fn from_ptr(ptr: NonNull) -> Self { ffi::ALooper_acquire(ptr.as_ptr()); @@ -232,7 +238,7 @@ impl ForeignLooper { /// See also [the NDK /// docs](https://developer.android.com/ndk/reference/group/looper.html#alooper_addfd). - // `ALooper_addFd won't dereference `data`; it will only pass it on to the event. + // `ALooper_addFd` won't dereference `data`; it will only pass it on to the event. // Optionally dereferencing it there already enforces `unsafe` context. #[allow(clippy::not_unsafe_ptr_arg_deref)] pub fn add_fd( diff --git a/ndk/src/media/image_reader.rs b/ndk/src/media/image_reader.rs index e0e498ec..97ab8bc9 100644 --- a/ndk/src/media/image_reader.rs +++ b/ndk/src/media/image_reader.rs @@ -1,3 +1,7 @@ +//! Bindings for [`AImageReader`] and [`AImage`] +//! +//! [`AImageReader`]: https://developer.android.com/ndk/reference/group/media#aimagereader +//! [`AImage`]: https://developer.android.com/ndk/reference/group/media#aimage #![cfg(feature = "api-level-24")] use super::NdkMediaError; @@ -46,6 +50,9 @@ pub type ImageListener = Box; #[cfg(feature = "hardware_buffer")] pub type BufferRemovedListener = Box; +/// A native [`AImageReader *`] +/// +/// [`AImageReader *`]: https://developer.android.com/ndk/reference/group/media#aimagereader pub struct ImageReader { inner: NonNull, image_cb: Option>, @@ -250,6 +257,9 @@ impl Drop for ImageReader { } } +/// A native [`AImage *`] +/// +/// [`AImage *`]: https://developer.android.com/ndk/reference/group/media#aimage #[derive(Debug)] pub struct Image { inner: NonNull, diff --git a/ndk/src/media/media_codec.rs b/ndk/src/media/media_codec.rs index 5cc860ca..f1745a36 100644 --- a/ndk/src/media/media_codec.rs +++ b/ndk/src/media/media_codec.rs @@ -1,3 +1,8 @@ +//! Bindings for [`AMediaFormat`] and [`AMediaCodec`] +//! +//! [`AMediaFormat`]: https://developer.android.com/ndk/reference/group/media#amediaformat +//! [`AMediaCodec`]: https://developer.android.com/ndk/reference/group/media#amediacodec + use super::{get_unlikely_to_be_null, NdkMediaError, Result}; use crate::native_window::NativeWindow; use std::{ @@ -15,6 +20,9 @@ pub enum MediaCodecDirection { Encoder, } +/// A native [`AMediaFormat *`] +/// +/// [`AMediaFormat *`]: https://developer.android.com/ndk/reference/group/media#amediaformat #[derive(Debug)] pub struct MediaFormat { inner: NonNull, @@ -180,6 +188,9 @@ impl Drop for MediaFormat { } } +/// A native [`AMediaCodec *`] +/// +/// [`AMediaCodec *`]: https://developer.android.com/ndk/reference/group/media#amediacodec #[derive(Debug)] pub struct MediaCodec { inner: NonNull, diff --git a/ndk/src/native_activity.rs b/ndk/src/native_activity.rs index 330eba26..22aca14b 100644 --- a/ndk/src/native_activity.rs +++ b/ndk/src/native_activity.rs @@ -1,7 +1,6 @@ -//! Bindings for `ANativeActivity` +//! Bindings for [`ANativeActivity`] //! -//! See also [the NDK -//! docs](https://developer.android.com/ndk/reference/struct/a-native-activity.html) +//! [`ANativeActivity`]: https://developer.android.com/ndk/reference/group/native-activity#anativeactivity use super::hardware_buffer_format::HardwareBufferFormat; use bitflags::bitflags; @@ -51,18 +50,18 @@ bitflags! { } } -/// An `ANativeActivity *` +/// A native [`ANativeActivity *`] /// -/// This is either provided in `ANativeActivity_onCreate`, or accessible in -/// `android_native_app_glue`'s android_app. +/// This is either provided in `ANativeActivity_onCreate`, or accessible through +/// `ndk_glue::native_activity()`. /// -/// +/// [`ANativeActivity *`]: https://developer.android.com/ndk/reference/struct/a-native-activity #[derive(Debug)] pub struct NativeActivity { ptr: NonNull, } -// It gets shared between threads in android_native_app_glue +// It gets shared between threads in `ndk-glue` unsafe impl Send for NativeActivity {} unsafe impl Sync for NativeActivity {} diff --git a/ndk/src/native_window.rs b/ndk/src/native_window.rs index d86c88e0..08ccec07 100644 --- a/ndk/src/native_window.rs +++ b/ndk/src/native_window.rs @@ -1,11 +1,19 @@ -//! Bindings for [`ffi::ANativeWindow`] +//! Bindings for [`ANativeWindow`] +//! +//! [`ANativeWindow`]: https://developer.android.com/ndk/reference/group/a-native-window#anativewindow pub use super::hardware_buffer_format::HardwareBufferFormat; use jni_sys::{jobject, JNIEnv}; use raw_window_handle::{AndroidNdkHandle, HasRawWindowHandle, RawWindowHandle}; use std::{convert::TryFrom, ffi::c_void, ptr::NonNull}; -/// +// [`NativeWindow`] represents the producer end of an image queue +/// +/// It is the C counterpart of the [`android.view.Surface`] object in Java, and can be converted +/// both ways. Depending on the consumer, images submitted to [`NativeWindow`] can be shown on the +/// display or sent to other consumers, such as video encoders. +/// +/// [`android.view.Surface`]: https://developer.android.com/reference/android/view/Surface #[derive(Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] pub struct NativeWindow { ptr: NonNull,