docs: Improve documentation on AppKit and UIKit variants

* Update availability hints to include visionOS.
* Use objc2 v0.6 in examples.
* Add more detailed examples of how to create UIKit and AppKit handles.

Author: madsmtm

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+* Improve documentation on AppKit and UIKit handles.
+
 ## 0.6.2 (2024-05-17)
 
 * Add OpenHarmony OS support (#164)

src/appkit.rs

@@ -57,25 +57,25 @@ impl DisplayHandle<'static> {
 /// # fn inner() {
 /// #![cfg(target_os = "macos")]
 /// # #[cfg(requires_objc2)]
-/// use objc2_app_kit::NSView;
+/// use objc2::MainThreadMarker;
 /// # #[cfg(requires_objc2)]
-/// use objc2_foundation::is_main_thread;
+/// use objc2::rc::Retained;
 /// # #[cfg(requires_objc2)]
-/// use objc2::rc::Id;
+/// use objc2_app_kit::NSView;
 /// use raw_window_handle::{WindowHandle, RawWindowHandle};
 ///
 /// let handle: WindowHandle<'_>; // Get the window handle from somewhere else
 /// # handle = unimplemented!();
 /// match handle.as_raw() {
 ///     # #[cfg(requires_objc2)]
 ///     RawWindowHandle::AppKit(handle) => {
-///         assert!(is_main_thread(), "can only access AppKit handles on the main thread");
+///         assert!(MainThreadMarker::new().is_some(), "can only access AppKit handles on the main thread");
 ///         let ns_view = handle.ns_view.as_ptr();
 ///         // SAFETY: The pointer came from `WindowHandle`, which ensures
 ///         // that the `AppKitWindowHandle` contains a valid pointer to an
 ///         // `NSView`.
 ///         // Unwrap is fine, since the pointer came from `NonNull`.
-///         let ns_view: Id<NSView> = unsafe { Id::retain(ns_view.cast()) }.unwrap();
+///         let ns_view: Retained<NSView> = unsafe { Retained::retain(ns_view.cast()) }.unwrap();
 ///         // Do something with the NSView here, like getting the `NSWindow`
 ///         let ns_window = ns_view.window().expect("view was not installed in a window");
 ///     }
@@ -96,14 +96,18 @@ impl AppKitWindowHandle {
     ///
     /// # Example
     ///
-    /// ```
-    /// # use core::ptr::NonNull;
-    /// # use raw_window_handle::AppKitWindowHandle;
-    /// # type NSView = ();
-    /// #
-    /// let view: &NSView;
-    /// # view = &();
-    /// let handle = AppKitWindowHandle::new(NonNull::from(view).cast());
+    /// Create a handle from the content view of a `NSWindow`.
+    ///
+    /// ```ignore
+    /// use std::ptr::NonNull;
+    /// use objc2::rc::Retained;
+    /// use objc2_app_kit::{NSWindow, NSView};
+    /// use raw_window_handle::AppKitWindowHandle;
+    ///
+    /// let ns_window: Retained<NSWindow> = ...;
+    /// let ns_view: Retained<NSView> = window.contentView();
+    /// let ns_view: NonNull<NSView> = NonNull::from(&*ns_view);
+    /// let handle = AppKitWindowHandle::new(ns_view.cast());
     /// ```
     pub fn new(ns_view: NonNull<c_void>) -> Self {
         Self { ns_view }

src/lib.rs

@@ -114,17 +114,17 @@ pub enum RawWindowHandle {
     /// A raw window handle for UIKit (Apple's non-macOS windowing library).
     ///
     /// ## Availability Hints
-    /// This variant is likely to be used on iOS, tvOS, (in theory) watchOS, and
-    /// Mac Catalyst (`$arch-apple-ios-macabi` targets, which can notably use
-    /// UIKit *or* AppKit), as these are the targets that (currently) support
-    /// UIKit.
+    /// This variant is used on iOS, tvOS, watchOS, visionOS, and Mac
+    /// Catalyst, as these are the targets that (currently) support UIKit.
+    ///
+    /// Note that Mac Catalyst (`$arch-apple-ios-macabi` targets), can use
+    /// UIKit *or* AppKit.
     UiKit(UiKitWindowHandle),
     /// A raw window handle for AppKit.
     ///
     /// ## Availability Hints
-    /// This variant is likely to be used on macOS, although Mac Catalyst
-    /// (`$arch-apple-ios-macabi` targets, which can notably use UIKit *or*
-    /// AppKit) can also use it despite being `target_os = "ios"`.
+    /// This variant is used on macOS, although Mac Catalyst can also use it
+    /// despite being `target_os = "ios"`.
     AppKit(AppKitWindowHandle),
     /// A raw window handle for the Redox operating system.
     ///
@@ -267,17 +267,17 @@ pub enum RawDisplayHandle {
     /// A raw display handle for UIKit (Apple's non-macOS windowing library).
     ///
     /// ## Availability Hints
-    /// This variant is likely to be used on iOS, tvOS, (in theory) watchOS, and
-    /// Mac Catalyst (`$arch-apple-ios-macabi` targets, which can notably use
-    /// UIKit *or* AppKit), as these are the targets that (currently) support
-    /// UIKit.
+    /// This variant is used on iOS, tvOS, watchOS, visionOS, and Mac
+    /// Catalyst, as these are the targets that (currently) support UIKit.
+    ///
+    /// Note that Mac Catalyst (`$arch-apple-ios-macabi` targets), can use
+    /// UIKit *or* AppKit.
     UiKit(UiKitDisplayHandle),
     /// A raw display handle for AppKit.
     ///
     /// ## Availability Hints
-    /// This variant is likely to be used on macOS, although Mac Catalyst
-    /// (`$arch-apple-ios-macabi` targets, which can notably use UIKit *or*
-    /// AppKit) can also use it despite being `target_os = "ios"`.
+    /// This variant is used on macOS, although Mac Catalyst can also use it
+    /// despite being `target_os = "ios"`.
     AppKit(AppKitDisplayHandle),
     /// A raw display handle for the Redox operating system.
     ///

src/uikit.rs

@@ -57,9 +57,9 @@ impl DisplayHandle<'static> {
 /// # fn inner() {
 /// #![cfg(any(target_os = "ios", target_os = "tvos", target_os = "watchos", target_os = "xros"))]
 /// # #[cfg(requires_objc2)]
-/// use objc2_foundation::is_main_thread;
+/// use objc2::MainThreadMarker;
 /// # #[cfg(requires_objc2)]
-/// use objc2::rc::Id;
+/// use objc2::rc::Retained;
 /// # #[cfg(requires_objc2)]
 /// use objc2_ui_kit::UIView;
 /// use raw_window_handle::{WindowHandle, RawWindowHandle};
@@ -69,13 +69,13 @@ impl DisplayHandle<'static> {
 /// match handle.as_raw() {
 ///     # #[cfg(requires_objc2)]
 ///     RawWindowHandle::UIKit(handle) => {
-///         assert!(is_main_thread(), "can only access UIKit handles on the main thread");
+///         assert!(MainThreadMarker::new().is_some(), "can only access UIKit handles on the main thread");
 ///         let ui_view = handle.ui_view.as_ptr();
 ///         // SAFETY: The pointer came from `WindowHandle`, which ensures
 ///         // that the `UiKitWindowHandle` contains a valid pointer to an
 ///         // `UIView`.
 ///         // Unwrap is fine, since the pointer came from `NonNull`.
-///         let ui_view: Id<UIView> = unsafe { Id::retain(ui_view.cast()) }.unwrap();
+///         let ui_view: Retained<UIView> = unsafe { Retained::retain(ui_view.cast()) }.unwrap();
 ///         // Do something with the UIView here.
 ///     }
 ///     handle => unreachable!("unknown handle {handle:?} for platform"),
@@ -97,15 +97,18 @@ impl UiKitWindowHandle {
     ///
     /// # Example
     ///
-    /// ```
-    /// # use core::ptr::NonNull;
-    /// # use raw_window_handle::UiKitWindowHandle;
-    /// # type UIView = ();
-    /// #
-    /// let view: &UIView;
-    /// # view = &();
-    /// let mut handle = UiKitWindowHandle::new(NonNull::from(view).cast());
-    /// // Optionally set the view controller.
+    /// Create a handle from a `UIView`.
+    ///
+    /// ```ignore
+    /// use std::ptr::NonNull;
+    /// use objc2::rc::Retained;
+    /// use objc2_ui_kit::UIView;
+    /// use raw_window_handle::UiKitWindowHandle;
+    ///
+    /// let ui_view: Retained<UIView> = ...;
+    /// let ui_view: NonNull<UIView> = NonNull::from(&*ui_view);
+    /// let mut handle = UiKitWindowHandle::new(ui_view.cast());
+    /// // Optionally, set the view controller too.
     /// handle.ui_view_controller = None;
     /// ```
     pub fn new(ui_view: NonNull<c_void>) -> Self {