From 1909ca5a965f67cae347180acbd231461b81d5d9 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Wed, 15 Jun 2022 22:04:19 +0200 Subject: [PATCH] Small documentation fixes --- objc2/src/lib.rs | 2 +- objc2/src/macros.rs | 35 ++++++++++++++++++----------------- objc2/src/rc/test_object.rs | 2 +- 3 files changed, 20 insertions(+), 19 deletions(-) diff --git a/objc2/src/lib.rs b/objc2/src/lib.rs index 01d386649..e69737580 100644 --- a/objc2/src/lib.rs +++ b/objc2/src/lib.rs @@ -107,7 +107,7 @@ //! //! To use this functionality, enable the `"verify_message"` cargo feature //! while debugging. With this feature enabled, encodings are checked every -//! time your send a message, and the message send will panic if they are not +//! time you send a message, and the message send will panic if they are not //! equivalent. //! //! To take the example above, if we changed the `hash` method's return type diff --git a/objc2/src/macros.rs b/objc2/src/macros.rs index f3739e102..8531a0ecf 100644 --- a/objc2/src/macros.rs +++ b/objc2/src/macros.rs @@ -71,10 +71,10 @@ macro_rules! sel { /// ``` /// /// This way we are clearly communicating to Rust that: The method -/// `doSomething:` works on shared references to an object. It takes a C-style -/// signed integer, and returns a pointer to what is probably a C-compatible -/// string. Now it's much, _much_ easier to make a safe abstraction around -/// this! +/// `doSomething:` works with a shared reference to the object. It takes a +/// C-style signed integer, and returns a pointer to what is probably a +/// C-compatible string. Now it's much, _much_ easier to make a safe +/// abstraction around this! /// /// There exists two variants of this macro, [`msg_send_bool!`] and /// [`msg_send_id!`], which can help with upholding certain requirements of @@ -94,9 +94,12 @@ macro_rules! sel { /// /// All arguments, and the return type, must implement [`Encode`]. /// -/// This translates into a call to [`sel!`], and afterwards a fully qualified -/// call to [`MessageReceiver::send_message`]. Note that this means that -/// auto-dereferencing of the receiver is not supported. +/// This macro translates into a call to [`sel!`], and afterwards a fully +/// qualified call to [`MessageReceiver::send_message`]. Note that this means +/// that auto-dereferencing of the receiver is not supported, and that the +/// receiver is consumed. You may encounter a little trouble with `&mut` +/// references, try refactoring into a separate method or reborrowing the +/// reference. /// /// Variadic arguments are currently not supported. /// @@ -127,10 +130,9 @@ macro_rules! sel { /// 1. The selector corresponds to a valid method that is available on the /// receiver. /// -/// 2. The argument types must match what the receiver excepts for this -/// selector. +/// 2. The argument types match what the receiver excepts for this selector. /// -/// 3. The return type must match what the receiver returns for this selector. +/// 3. The return type match what the receiver returns for this selector. /// /// 4. The call must not violate Rust's mutability rules, for example if /// passing an `&T`, the Objective-C method must not mutate the variable @@ -166,9 +168,9 @@ macro_rules! sel { /// # let obj: *mut Object = 0 as *mut Object; /// let description: *const Object = unsafe { msg_send![obj, description] }; /// // Usually you'd use msg_send_id here ^ -/// let _: () = unsafe { msg_send![obj, setArg1: 1 arg2: 2] }; -/// // Or with an optional comma between arguments: -/// let _: () = unsafe { msg_send![obj, setArg1: 1, arg2: 2] }; +/// let _: () = unsafe { msg_send![obj, setArg1: 1u32, arg2: 2i32] }; +/// let arg1: i32 = unsafe { msg_send![obj, getArg1] }; +/// let arg2: i32 = unsafe { msg_send![obj, getArg2] }; /// ``` #[macro_export] macro_rules! msg_send { @@ -263,7 +265,7 @@ macro_rules! msg_send_bool { /// [`msg_send!`] for methods returning `id`, `NSObject*`, or similar object /// pointers. /// -/// Objective-C's object pointers have certain rules for when they should be +/// Object pointers in Objective-C have certain rules for when they should be /// retained and released across function calls. This macro helps doing that, /// and returns an [`Option`] (letting you handle failures) containing an /// [`rc::Id`] with the object. @@ -333,10 +335,9 @@ macro_rules! msg_send_bool { /// pools! /// /// See [the clang documentation][arc-retainable] for the precise -/// specification. +/// specification of Objective-C's ownership rules. /// /// This macro doesn't support super methods yet, see [#173]. -/// /// The `retain`, `release` and `autorelease` selectors are not supported, use /// [`Id::retain`], [`Id::drop`] and [`Id::autorelease`] for that. /// @@ -402,7 +403,7 @@ macro_rules! msg_send_id { }); } -/// Helper macro: To avoid exposing these in the docs for [`msg_send_id!`]. +/// Helper macro to avoid exposing these in the docs for [`msg_send_id!`]. #[doc(hidden)] #[macro_export] macro_rules! __msg_send_id_helper { diff --git a/objc2/src/rc/test_object.rs b/objc2/src/rc/test_object.rs index 90d66540e..6db124120 100644 --- a/objc2/src/rc/test_object.rs +++ b/objc2/src/rc/test_object.rs @@ -152,7 +152,7 @@ impl RcTestObject { } pub(crate) fn new() -> Id { - // Use msg_send! to test that; msg_send_id! is tested elsewhere! + // Use msg_send! - msg_send_id! is tested elsewhere! unsafe { Id::new(msg_send![Self::class(), new]) }.unwrap() } }