Merge pull request #492 from madsmtm/icrate-documentation-examples

Improve documentation

Author: madsmtm

crates/icrate/Cargo.toml

@@ -132,8 +132,9 @@ unstable-example-delegate = [
     "apple",
     "Foundation",
     "Foundation_NSString",
+    "Foundation_NSNotification",
     "AppKit",
-    "AppKit_NSResponder",
+    "AppKit_NSApplication",
 ]
 unstable-example-speech_synthesis = [
     "apple",

crates/icrate/README.md

@@ -5,11 +5,9 @@
 [![Documentation](https://docs.rs/icrate/badge.svg)](https://docs.rs/icrate/)
 [![CI](https://github.com/madsmtm/objc2/actions/workflows/ci.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/ci.yml)
 
-Rust bindings to Apple's frameworks..
+Rust bindings to Apple's frameworks.
 
-This crate is part of the [`objc2` project](https://github.com/madsmtm/objc2),
-see that for related crates, or see [the docs](https://docs.rs/icrate/) for
-more details.
+This README is kept intentionally small in an effort to consolidate the documentation, see [the Rust docs](https://docs.rs/icrate/) for more details.
 
 
 ## Supported versions
@@ -22,20 +20,3 @@ Currently supports:
 - iOS/iPadOS: `7.0-16.2` (WIP)
 - tvOS: `9.0-16.1` (WIP)
 - watchOS: `1.0-9.1` (WIP)
-
-
-## Example
-
-```rust
-use icrate::Foundation::{ns_string, NSCopying, NSArray};
-
-let string = ns_string!("world");
-println!("hello {string}");
-
-let array = NSArray::from_id_slice(&[string.copy()]);
-println!("{array:?}");
-```
-
-More examples are [available in the repository][examples].
-
-[examples]: https://github.com/madsmtm/objc2/tree/master/crates/icrate/examples

crates/icrate/examples/browser.rs

@@ -1,6 +1,4 @@
 #![deny(unsafe_op_in_unsafe_fn)]
-#![cfg_attr(not(target_os = "macos"), allow(unused))]
-
 use core::{cell::RefCell, ptr::NonNull};
 
 use icrate::{

crates/icrate/examples/delegate.rs

@@ -1,22 +1,19 @@
 #![deny(unsafe_op_in_unsafe_fn)]
-#![cfg_attr(not(target_os = "macos"), allow(unused))]
 use std::ptr::NonNull;
 
-use icrate::Foundation::{ns_string, NSCopying, NSObject, NSString};
+use icrate::AppKit::{NSApplication, NSApplicationActivationPolicyRegular, NSApplicationDelegate};
+use icrate::Foundation::{
+    ns_string, NSCopying, NSNotification, NSObject, NSObjectProtocol, NSString,
+};
 use objc2::declare::{Ivar, IvarBool, IvarDrop, IvarEncode};
 use objc2::rc::Id;
-use objc2::runtime::AnyObject;
+use objc2::runtime::ProtocolObject;
 use objc2::{declare_class, msg_send, msg_send_id, mutability, ClassType};
 
-#[cfg(target_os = "macos")]
-#[link(name = "AppKit", kind = "framework")]
-extern "C" {}
-
-#[cfg(target_os = "macos")]
 declare_class!(
     #[derive(Debug)]
-    struct CustomAppDelegate {
-        pub ivar: IvarEncode<u8, "_ivar">,
+    struct AppDelegate {
+        ivar: IvarEncode<u8, "_ivar">,
         another_ivar: IvarBool<"_another_ivar">,
         box_ivar: IvarDrop<Box<i32>, "_box_ivar">,
         maybe_box_ivar: IvarDrop<Option<Box<i32>>, "_maybe_box_ivar">,
@@ -26,14 +23,14 @@ declare_class!(
 
     mod ivars;
 
-    unsafe impl ClassType for CustomAppDelegate {
+    unsafe impl ClassType for AppDelegate {
         #[inherits(NSObject)]
         type Super = icrate::AppKit::NSResponder;
         type Mutability = mutability::InteriorMutable;
-        const NAME: &'static str = "MyCustomAppDelegate";
+        const NAME: &'static str = "MyAppDelegate";
     }
 
-    unsafe impl CustomAppDelegate {
+    unsafe impl AppDelegate {
         #[method(initWith:another:)]
         unsafe fn init_with(
             this: *mut Self,
@@ -42,70 +39,56 @@ declare_class!(
         ) -> Option<NonNull<Self>> {
             let this: Option<&mut Self> = unsafe { msg_send![super(this), init] };
 
-            // TODO: `ns_string` can't be used inside closures; investigate!
-            let s = ns_string!("def");
-
             this.map(|this| {
                 Ivar::write(&mut this.ivar, ivar);
-                *this.another_ivar = another_ivar;
-                *this.maybe_box_ivar = None;
-                *this.maybe_id_ivar = Some(s.copy());
+                Ivar::write(&mut this.another_ivar, another_ivar);
+                Ivar::write(&mut this.maybe_box_ivar, None);
+                Ivar::write(&mut this.maybe_id_ivar, Some(ns_string!("def").copy()));
                 Ivar::write(&mut this.box_ivar, Box::new(2));
                 Ivar::write(&mut this.id_ivar, NSString::from_str("abc"));
                 NonNull::from(this)
             })
         }
-
-        #[method(myClassMethod)]
-        fn my_class_method() {
-            println!("A class method!");
-        }
     }
 
-    // For some reason, `NSApplicationDelegate` is not a "real" protocol we
-    // can retrieve using `objc_getProtocol` - it seems it is created by
-    // `clang` only when used in Objective-C...
-    //
-    // TODO: Investigate this!
-    unsafe impl CustomAppDelegate {
-        /// This is `unsafe` because it expects `sender` to be valid
+    unsafe impl NSApplicationDelegate for AppDelegate {
         #[method(applicationDidFinishLaunching:)]
-        unsafe fn did_finish_launching(&self, sender: *mut AnyObject) {
+        fn did_finish_launching(&self, notification: &NSNotification) {
             println!("Did finish launching!");
-            // Do something with `sender`
-            dbg!(sender);
+            // Do something with the notification
+            dbg!(notification);
         }
 
-        /// Some comment before `sel`.
         #[method(applicationWillTerminate:)]
-        /// Some comment after `sel`.
-        fn will_terminate(&self, _: *mut AnyObject) {
+        fn will_terminate(&self, _notification: &NSNotification) {
             println!("Will terminate!");
         }
     }
 );
 
-#[cfg(target_os = "macos")]
-impl CustomAppDelegate {
+unsafe impl NSObjectProtocol for AppDelegate {}
+
+impl AppDelegate {
     pub fn new(ivar: u8, another_ivar: bool) -> Id<Self> {
         unsafe { msg_send_id![Self::alloc(), initWith: ivar, another: another_ivar] }
     }
 }
 
-#[cfg(target_os = "macos")]
 fn main() {
-    let delegate = CustomAppDelegate::new(42, true);
+    let app = unsafe { NSApplication::sharedApplication() };
+    unsafe { app.setActivationPolicy(NSApplicationActivationPolicyRegular) };
+
+    // initialize the delegate
+    let delegate = AppDelegate::new(42, true);
 
     println!("{delegate:?}");
-    println!("{:?}", delegate.ivar);
-    println!("{:?}", delegate.another_ivar);
-    println!("{:?}", delegate.box_ivar);
-    println!("{:?}", delegate.maybe_box_ivar);
-    println!("{:?}", delegate.id_ivar);
-    println!("{:?}", delegate.maybe_id_ivar);
-}
 
-#[cfg(not(target_os = "macos"))]
-fn main() {
-    panic!("This example uses AppKit, which is only present on macOS");
+    // configure the application delegate
+    unsafe {
+        let object = ProtocolObject::from_ref(&*delegate);
+        app.setDelegate(Some(object));
+    };
+
+    // run the app
+    unsafe { app.run() };
 }

crates/icrate/src/AppKit/mod.rs

@@ -1,3 +1,20 @@
+//! # Bindings to the `AppKit` framework
+//!
+//!
+//! ## Examples
+//!
+//! Implementing `NSApplicationDelegate` for a custom class.
+//!
+//! ```ignore
+#![doc = include_str!("../../examples/delegate.rs")]
+//! ```
+//!
+//! An example showing basic and a bit more advanced usage of `NSPasteboard`.
+//!
+//! ```ignore
+#![doc = include_str!("../../examples/nspasteboard.rs")]
+//! ```
+
 mod fixes;
 #[path = "../generated/AppKit/mod.rs"]
 mod generated;

crates/icrate/src/Foundation/mod.rs

@@ -73,6 +73,21 @@
 //! | `NSMutableDictionary<K, V>*` | `HashMap<K, V>` |
 //! | `NSEnumerator<T>*` | `Box<dyn Iterator<T>>` |
 //! | `NSCopying*` | `Box<dyn Clone>` |
+//!
+//!
+//! ## Examples
+//!
+//! Basic usage of a few Foundation types.
+//!
+//! ```ignore
+#![doc = include_str!("../../examples/basic_usage.rs")]
+//! ```
+//!
+//! An example showing how to define your own interfaces to parts that may be missing in `icrate`.
+//!
+//! ```ignore
+#![doc = include_str!("../../examples/speech_synthesis.rs")]
+//! ```
 #![allow(unused_imports)]
 
 #[doc(hidden)]

crates/icrate/src/Metal/mod.rs

@@ -1,3 +1,13 @@
+//! # Bindings to the `Metal` framework
+//!
+//!
+//! ## Examples
+//!
+//! Drawing a rotating triangle.
+//!
+//! ```ignore
+#![doc = include_str!("../../examples/metal.rs")]
+//! ```
 #![allow(unused_imports)]
 
 mod capture;

crates/icrate/src/WebKit/mod.rs

@@ -1,3 +1,11 @@
+//! # Bindings to the `WebKit` framework
+//!
+//!
+//! ## Examples
+//!
+//! ```ignore
+#![doc = include_str!("../../examples/browser.rs")]
+//! ```
 mod fixes;
 #[path = "../generated/WebKit/mod.rs"]
 mod generated;

crates/icrate/src/lib.rs

@@ -1,8 +1,47 @@
 //! # Bindings to Apple's frameworks
 //!
-//! This crate is a mostly autogenerated interface to some of Apple's
-//! frameworks. It builds upon [`objc2`] to provide memory management and
-//! safety in many areas; see that crate for more details.
+//! `icrate` is an autogenerated interface to Apple's Objective-C frameworks
+//! like AppKit, Foundation, Metal, WebKit, and so on.
+//!
+//! The bindings currently contain very little documentation, you should view
+//! [Apple's developer documentation][apple-doc-index] for detailed
+//! information about each API. (There are [plans][#309] for importing that
+//! documentation here).
+//!
+//! [#309]: https://github.com/madsmtm/objc2/issues/309
+//! [apple-doc-index]: https://developer.apple.com/documentation/technologies
+//!
+//!
+//! ## Example
+//!
+//! ```console
+//! $ cargo add icrate --features=Foundation,Foundation_all
+//! ```
+//!
+#![cfg_attr(
+    all(
+        feature = "Foundation",
+        feature = "Foundation_NSArray",
+        feature = "Foundation_NSString"
+    ),
+    doc = "```"
+)]
+#![cfg_attr(
+    not(all(
+        feature = "Foundation",
+        feature = "Foundation_NSArray",
+        feature = "Foundation_NSString"
+    )),
+    doc = "```ignore"
+)]
+//! use icrate::Foundation::{ns_string, NSCopying, NSArray};
+//!
+//! let string = ns_string!("world");
+//! println!("hello {string}");
+//!
+//! let array = NSArray::from_id_slice(&[string.copy()]);
+//! println!("{array:?}");
+//! ```
 
 #![no_std]
 #![cfg_attr(feature = "unstable-docsrs", feature(doc_auto_cfg))]
@@ -34,11 +73,6 @@ extern crate std;
 
 #[cfg(doctest)]
 #[doc = include_str!("../README.md")]
-#[cfg(all(
-    feature = "Foundation",
-    feature = "Foundation_NSString",
-    feature = "Foundation_NSArray"
-))]
 extern "C" {}
 
 #[cfg(feature = "objective-c")]

crates/objc2/src/mutability.rs

@@ -104,6 +104,12 @@ pub struct Mutable {
 /// The mutable counterpart must be specified as the type parameter `MS` to
 /// allow `NSCopying` and `NSMutableCopying` to return the correct type.
 ///
+/// Functionality that is provided with this:
+/// - [`IsIdCloneable`].
+/// - [`IsAllocableAnyThread`].
+/// - You are allowed to hand out pointers / references to an instance's
+///   internal data, since you know such data will never be mutated.
+///
 ///
 /// # Example
 ///
@@ -259,7 +265,11 @@ impl<IS: ?Sized> Mutability for MutableWithImmutableSuperclass<IS> {}
 impl Mutability for InteriorMutable {}
 impl Mutability for MainThreadOnly {}
 
-/// Marker trait for classes where [`Id::clone`][clone-id] is safe.
+/// Marker trait for classes where [`Id::clone`] is safe.
+///
+/// Since the `Foundation` collection types (`NSArray<T>`,
+/// `NSDictionary<K, V>`, ...) act as if they store [`Id`]s, this also makes
+/// certain functionality on those types possible.
 ///
 /// This is implemented for classes whose [`ClassType::Mutability`] is one of:
 /// - [`Root`].
@@ -268,19 +278,24 @@ impl Mutability for MainThreadOnly {}
 /// - [`InteriorMutable`].
 /// - [`MainThreadOnly`].
 ///
-/// [clone-id]: crate::rc::Id#impl-Clone-for-Id<T>
+/// [`Id`]: crate::rc::Id
+/// [`Id::clone`]: crate::rc::Id#impl-Clone-for-Id<T>
 pub trait IsIdCloneable: ClassType {}
 impl<T: ?Sized + ClassType> IsIdCloneable for T where T::Mutability: private::MutabilityIsIdCloneable
 {}
 
-/// Marker trait for classes where the [`retain`] selector is always safe.
+/// Marker trait for classes where the `retain` selector is always safe.
+///
+/// [`Id::clone`] takes `&Id<T>`, while [`ClassType::retain`] only takes `&T`;
+/// the difference between these two is that in the former case, you know that
+/// there are no live mutable subclasses.
 ///
 /// This is implemented for classes whose [`ClassType::Mutability`] is one of:
 /// - [`Immutable`].
 /// - [`InteriorMutable`].
 /// - [`MainThreadOnly`].
 ///
-/// [`retain`]: ClassType::retain
+/// [`Id::clone`]: crate::rc::Id#impl-Clone-for-Id<T>
 pub trait IsRetainable: IsIdCloneable {}
 impl<T: ?Sized + ClassType> IsRetainable for T where T::Mutability: private::MutabilityIsRetainable {}