Include examples in objc2 documentation

Author: madsmtm

crates/objc2/examples/class_with_lifetime.rs

@@ -1,7 +1,5 @@
-//! A custom Objective-C class with a lifetime parameter.
-//!
-//! Note that we can't use the `declare_class!` macro for this, it doesn't
-//! support such use-cases. Instead, we'll declare the class manually!
+//! Note: We can't use the `declare_class!` macro for this, it doesn't support
+//! such use-cases (yet). Instead, we'll declare the class manually.
 #![deny(unsafe_op_in_unsafe_fn)]
 use std::marker::PhantomData;
 use std::sync::Once;
@@ -45,11 +43,11 @@ unsafe impl RefEncode for MyObject<'_> {
 unsafe impl Message for MyObject<'_> {}
 
 impl<'a> MyObject<'a> {
-    unsafe extern "C" fn init_with_ptr(
-        &mut self,
+    unsafe extern "C" fn init_with_ptr<'s>(
+        &'s mut self,
         _cmd: Sel,
         ptr: Option<&'a mut u8>,
-    ) -> Option<&'a mut Self> {
+    ) -> Option<&'s mut Self> {
         let this: Option<&mut Self> = unsafe { msg_send![super(self), init] };
         this.map(|this| {
             // Properly initialize the number reference
@@ -112,23 +110,30 @@ unsafe impl<'a> ClassType for MyObject<'a> {
 
 fn main() {
     let mut number = 54;
+
     let mut obj = MyObject::new(&mut number);
+    assert_eq!(*obj.get(), 54);
 
-    // It is not possible to convert to `Id<NSObject>` since that would loose
+    // It is not possible to convert to `Id<NSObject>`, since that would loose
     // the lifetime information that `MyObject` stores.
+    //
     // let obj = Id::into_super(obj);
     //
-    // Neither is it possible to clone the object, since it is marked as
-    // `Mutable` in `ClassType::Mutability`.
+    // Neither is it possible to clone or retain the object, since it is
+    // marked as `Mutable` in `ClassType::Mutability`.
+    //
     // let obj2 = obj.clone();
+    //
+    // Finally, it is not possible to access `number` any more, since `obj`
+    // holds a mutable reference to it.
+    //
+    // assert_eq!(number, 7);
 
-    println!("Number: {}", obj.get());
-
+    // But we can now mutate the referenced `number`
     obj.set(7);
-    // Won't compile, since `obj` holds a mutable reference to number
-    // println!("Number: {}", number);
-    println!("Number: {}", obj.get());
+    assert_eq!(*obj.get(), 7);
 
     drop(obj);
-    println!("Number: {number}");
+    // And now that we've dropped `obj`, we can access `number` again
+    assert_eq!(number, 7);
 }

crates/objc2/examples/encode_core_graphics.rs

@@ -2,7 +2,6 @@ use objc2::encode::{Encode, Encoding};
 
 #[cfg(target_pointer_width = "32")]
 type CGFloat = f32;
-
 #[cfg(target_pointer_width = "64")]
 type CGFloat = f64;
 
@@ -12,6 +11,7 @@ struct CGPoint {
     y: CGFloat,
 }
 
+// SAFETY: The struct is `repr(C)`, and the encoding is correct.
 unsafe impl Encode for CGPoint {
     const ENCODING: Encoding = Encoding::Struct("CGPoint", &[CGFloat::ENCODING, CGFloat::ENCODING]);
 }
@@ -22,6 +22,7 @@ struct CGSize {
     height: CGFloat,
 }
 
+// SAFETY: The struct is `repr(C)`, and the encoding is correct.
 unsafe impl Encode for CGSize {
     const ENCODING: Encoding = Encoding::Struct("CGSize", &[CGFloat::ENCODING, CGFloat::ENCODING]);
 }
@@ -32,10 +33,17 @@ struct CGRect {
     size: CGSize,
 }
 
+// SAFETY: The struct is `repr(C)`, and the encoding is correct.
 unsafe impl Encode for CGRect {
     const ENCODING: Encoding = Encoding::Struct("CGRect", &[CGPoint::ENCODING, CGSize::ENCODING]);
 }
 
 fn main() {
-    println!("{}", CGRect::ENCODING);
+    let expected = if cfg!(target_pointer_width = "64") {
+        "{CGRect={CGPoint=dd}{CGSize=dd}}"
+    } else {
+        "{CGRect={CGPoint=ff}{CGSize=ff}}"
+    };
+
+    assert!(CGRect::ENCODING.equivalent_to_str(expected));
 }

crates/objc2/examples/encode_ns_string.rs

@@ -0,0 +1,26 @@
+use objc2::encode::{Encode, Encoding, RefEncode};
+use objc2::runtime::Object;
+
+#[repr(transparent)]
+struct NSString {
+    // `NSString` has the same layout / works the same as `Object`.
+    _priv: Object,
+}
+
+// We don't know the size of NSString, so we can only hold pointers to it.
+//
+// SAFETY: The string is `repr(transparent)` over `Object`.
+unsafe impl RefEncode for NSString {
+    const ENCODING_REF: Encoding = Encoding::Object;
+}
+
+fn main() {
+    // The `RefEncode` implementation provide an `Encode` implementation for
+    // pointers to the object.
+    assert_eq!(<*const NSString>::ENCODING, Encoding::Object);
+    assert_eq!(<*mut NSString>::ENCODING, Encoding::Object);
+    assert_eq!(<&NSString>::ENCODING, Encoding::Object);
+    assert_eq!(<&mut NSString>::ENCODING, Encoding::Object);
+    assert_eq!(<Option<&NSString>>::ENCODING, Encoding::Object);
+    assert_eq!(<Option<&mut NSString>>::ENCODING, Encoding::Object);
+}

crates/objc2/examples/encode_nsstring.rs

@@ -1,27 +1,25 @@
-//! Implementing `Encode` and `RefEncode` for `NSUInteger`.
-//!
-//! Note that in this case `NSUInteger` could actually just be a type alias
-//! for `usize`, and that's already available under `objc2::ffi::NSUInteger`.
 use objc2::encode::{Encode, Encoding, RefEncode};
 
+// Note: In this case `NSUInteger` could actually just be a type alias for
+// `usize`, and actually that's already available as `objc2::ffi::NSUInteger`.
 #[repr(transparent)]
 struct NSUInteger {
     _inner: usize,
 }
 
 // SAFETY: `NSUInteger` has the same `repr` as `usize`.
 unsafe impl Encode for NSUInteger {
-    /// Running `@encode(NSUInteger)` gives `Q` on 64-bit systems and `I` on
-    /// 32-bit systems. This corresponds exactly to `usize`, which is also how
-    /// we've defined our struct.
+    // Running `@encode(NSUInteger)` gives `Q` on 64-bit systems and `I` on
+    // 32-bit systems. This corresponds exactly to `usize`, which is also how
+    // we've defined our struct.
     const ENCODING: Encoding = usize::ENCODING;
 }
 
 // SAFETY: `&NSUInteger` has the same representation as `&usize`.
 unsafe impl RefEncode for NSUInteger {
-    /// Running `@encode(NSUInteger*)` gives `^Q` on 64-bit systems and `^I`
-    /// on 32-bit systems. So implementing `RefEncode` as a plain pointer is
-    /// correct.
+    // Running `@encode(NSUInteger*)` gives `^Q` on 64-bit systems and `^I` on
+    // 32-bit systems. So implementing `RefEncode` as a plain pointer is
+    // correct.
     const ENCODING_REF: Encoding = Encoding::Pointer(&NSUInteger::ENCODING);
 }
 

crates/objc2/examples/encode_ns_uinteger.rs renamed to crates/objc2/examples/encode_nsuinteger.rs

@@ -1,20 +1,23 @@
-//! Implementing `RefEncode` for `NSDecimal`.
 use objc2::encode::{Encoding, RefEncode};
 
-/// We choose in this case to represent `NSDecimal` as an opaque struct
-/// (and in the future as an `extern type`) because we don't know much
-/// about the internals.
-///
-/// Therefore we do not implement `Encode`, but when implementing `RefEncode`
-/// the type-encoding still has to be correct.
+// We choose in this case to represent `NSDecimal` as an opaque struct because
+// we don't know much about the internals.
+//
+// Therefore we do not implement `Encode`, but when implementing `RefEncode`,
+// the type-encoding still has to be correct.
 #[repr(C)]
 struct NSDecimal {
+    // Note: This should be an [extern type][rfc-1861] instead, when that
+    // becomes possible, for now we use this as a workaround.
+    //
+    // [rfc-1861]: https://rust-lang.github.io/rfcs/1861-extern-types.html
     _priv: [u8; 0],
 }
 
-// SAFETY: `&NSDecimal` is a pointer.
+// SAFETY: `&NSDecimal` is a valid pointer, and the encoding is correct.
 unsafe impl RefEncode for NSDecimal {
-    // Running `@encode` on `NSDecimal*` on my 64-bit system gives `^{?=cCCC[38C]}`.
+    // Running `@encode` on `NSDecimal*` on my 64-bit system gives
+    // `^{?=cCCC[38C]}`. On other systems it may be something else!
     const ENCODING_REF: Encoding = Encoding::Pointer(&Encoding::Struct(
         "?",
         &[

crates/objc2/examples/encode_opaque_type.rs

@@ -43,31 +43,68 @@ use crate::Message;
 /// Use the trait to access the [`Class`] of an object.
 ///
 /// ```
-/// use objc2::ClassType;
-/// use objc2::runtime::NSObject;
+/// use objc2::{ClassType, msg_send_id};
+/// use objc2::rc::Id;
+/// # use objc2::runtime::{NSObject as MyObject};
+///
+/// // Get the class of the object.
+/// let cls = <MyObject as ClassType>::class();
+/// // Or, since the trait is in scope, just:
+/// let cls = MyObject::class();
+///
+/// // We can now access properties of the class.
+/// assert_eq!(cls.name(), MyObject::NAME);
+///
+/// // And we can send messages to the class.
+/// //
+/// // SAFETY:
+/// // - The class is `MyObject`, which can safely be initialized with `new`.
+/// // - The return type is correctly specified.
+/// let obj: Id<MyObject> = unsafe { msg_send_id![cls, new] };
+/// ```
+///
+/// Use the trait to allocate a new instance of an object.
+///
+/// ```
+/// use objc2::{ClassType, msg_send_id};
+/// use objc2::rc::Id;
+/// # use objc2::runtime::{NSObject as MyObject};
+///
+/// let obj = MyObject::alloc();
 ///
-/// // Get the class of `NSObject`
-/// let cls = <NSObject as ClassType>::class(); // Or just `NSObject::class()`
-/// assert_eq!(cls.name(), NSObject::NAME);
+/// // Now we can call initializers on this newly allocated object.
+/// //
+/// // SAFETY: `MyObject` can safely be initialized with `init`.
+/// let obj: Id<MyObject> = unsafe { msg_send_id![obj, init] };
 /// ```
 ///
-/// Use the [`extern_class!`][crate::extern_class] macro to implement this
-/// trait for a type.
+/// Use the [`extern_class!`][crate::extern_class] macro to easily implement
+/// this trait for a type.
 ///
-/// ```no_run
+/// ```
 /// use objc2::runtime::NSObject;
 /// use objc2::{extern_class, mutability, ClassType};
 ///
 /// extern_class!(
 ///     struct MyClass;
 ///
+///     // SAFETY: The superclass and the mutability is correctly specified.
 ///     unsafe impl ClassType for MyClass {
 ///         type Super = NSObject;
 ///         type Mutability = mutability::InteriorMutable;
+///         # // For testing purposes
+///         # const NAME: &'static str = "NSObject";
 ///     }
 /// );
 ///
 /// let cls = MyClass::class();
+/// let obj = MyClass::alloc();
+/// ```
+///
+/// Implement the trait manually for a class with a lifetime parameter.
+///
+/// ```
+#[doc = include_str!("../examples/class_with_lifetime.rs")]
 /// ```
 pub unsafe trait ClassType: Message {
     /// The superclass of this class.

crates/objc2/src/class_type.rs

@@ -9,7 +9,7 @@
 //! what Objective-C type-encodings are.
 //!
 //!
-//! ## Example
+//! ## Examples
 //!
 //! Implementing [`Encode`] and [`RefEncode`] for a custom type:
 //!
@@ -43,21 +43,33 @@
 //! assert!(MyStruct::ENCODING_REF.equivalent_to_str("^{MyStruct=fs}"));
 //! ```
 //!
-//! See the [`examples`] folder for more complex usage.
+//! Implementing [`Encode`] for a few core-graphics types.
 //!
-//! [`examples`]: https://github.com/madsmtm/objc2/tree/master/crates/objc2/examples
+//! Note that these are available in `icrate`, so the implementation here is
+//! mostly for demonstration.
 //!
+//! ```
+#![doc = include_str!("../../examples/encode_core_graphics.rs")]
+//! ```
+//!
+//! Implementing [`Encode`] and [`RefEncode`] for a transparent newtype.
+//!
+//! ```
+#![doc = include_str!("../../examples/encode_nsuinteger.rs")]
+//! ```
 //!
-//! ## Caveats
+//! Implementing [`RefEncode`] for an object, in this case `NSString`.
 //!
-//! We've taken the pragmatic approach with [`Encode`] and [`RefEncode`], and
-//! have implemented it for as many types as possible (instead of defining a
-//! bunch of subtraits for very specific purposes). However, that might
-//! sometimes be slightly surprising.
+//! ```
+#![doc = include_str!("../../examples/encode_nsstring.rs")]
+//! ```
 //!
-//! The primary example is [`()`][`unit`], which doesn't make sense as a
-//! method argument, but is a very common return type, and hence implements
-//! [`Encode`].
+//! Implementing [`RefEncode`] for a type where you don't necessarily know
+//! about the exact internals / the internals are not representable in Rust.
+//!
+//! ```
+#![doc = include_str!("../../examples/encode_opaque_type.rs")]
+//! ```
 
 use core::cell::{Cell, UnsafeCell};
 use core::ffi::c_void;
@@ -82,6 +94,7 @@ pub use objc2_encode::{Encoding, EncodingBox, ParseError};
 /// If your type is an opaque type you should not need to implement this;
 /// there you will only need [`RefEncode`].
 ///
+///
 /// # Safety
 ///
 /// The type must be FFI-safe, meaning a C-compatible `repr` (`repr(C)`,
@@ -99,6 +112,7 @@ pub use objc2_encode::{Encoding, EncodingBox, ParseError};
 /// passed to Objective-C via. `objc2::msg_send!` their destructor will not be
 /// called!
 ///
+///
 /// # Examples
 ///
 /// Implementing for a struct:
@@ -149,6 +163,7 @@ pub unsafe trait Encode {
 /// - `Option<&mut T>`
 /// - `Option<NonNull<T>>`
 ///
+///
 /// # Reasoning behind this trait's existence
 ///
 /// External crates cannot implement [`Encode`] for pointers or [`Option`]s
@@ -159,6 +174,7 @@ pub unsafe trait Encode {
 /// Finally, having this trait allows for much cleaner generic code that need
 /// to represent types that can be encoded as pointers.
 ///
+///
 /// # Safety
 ///
 /// References to the object must be FFI-safe.