diff --git a/crates/block-sys/README.md b/crates/block-sys/README.md index 9802c32a6..e26a2ae24 100644 --- a/crates/block-sys/README.md +++ b/crates/block-sys/README.md @@ -13,24 +13,27 @@ see that for related crates. ## Runtime Support -This library is basically just a raw interface to the aptly specified [Blocks -ABI](https://clang.llvm.org/docs/Block-ABI-Apple.html). However, different -runtime implementations exist and act in slightly different ways (and have -several different helper functions), the most important aspect being that the -libraries are named differently, so the linking must take that into account. - -The user can choose the desired runtime by using the relevant cargo feature -flags, see the following sections (might have to disable the default `apple` +This library is a raw interface to the aptly specified [Blocks ABI][abi]. +However, different runtime implementations exist and act in slightly different +ways (and have several different helper functions), the most important aspect +being that the libraries are named differently, so the linking must take that +into account. + +You can choose the desired runtime by using the relevant cargo feature flags, +see the following sections (you might have to disable the default `apple` feature first). Note that if the `objc-sys` crate is present in the module tree, this should have the same feature flag enabled as that. +[abi]: https://clang.llvm.org/docs/Block-ABI-Apple.html + + ### Apple's [`libclosure`](https://github.com/apple-oss-distributions/libclosure) - Feature flag: `apple`. -This is naturally the most sophisticated runtime, and it has quite a lot more -features than the specification mandates. This is used by default. +This is the most sophisticated runtime, and it has quite a lot more features +than the specification mandates. It is used by default. The minimum required operating system versions are as follows: - macOS: `10.6` @@ -45,11 +48,11 @@ Though in practice Rust itself requires higher versions than this. - Feature flag: `compiler-rt`. -This is effectively just a copy of Apple's older (around macOS 10.6) runtime, -and is now used in [Swift's `libdispatch`] and [Swift's Foundation] as well. +This is a copy of Apple's older (around macOS 10.6) runtime, and is now used +in [Swift's `libdispatch`] and [Swift's Foundation] as well. -This can be easily used on many Linux systems with the `libblocksruntime-dev` -package. +The runtime and associated headers can be installed on many Linux systems with +the `libblocksruntime-dev` package. Using this runtime probably won't work together with `objc-sys` crate. @@ -77,8 +80,8 @@ Sources: **Unstable: Hasn't been tested on Windows yet!** -Essentially just [a fork](https://github.com/microsoft/libobjc2) based on -GNUStep's `libobjc2` version 1.8. +[A fork](https://github.com/microsoft/libobjc2) based on GNUStep's `libobjc2` +version 1.8. ### [`ObjFW`](https://github.com/ObjFW/ObjFW) diff --git a/crates/block-sys/build.rs b/crates/block-sys/build.rs index e4131d934..72bfa1c87 100644 --- a/crates/block-sys/build.rs +++ b/crates/block-sys/build.rs @@ -30,11 +30,12 @@ fn main() { match (apple, compiler_rt, gnustep, objfw) { (true, false, false, false) => { - // Link to libclosure (internally called libsystem_blocks), which is - // exported by libSystem.dylib. + // Link to libclosure (internally called libsystem_blocks), which + // is exported by libSystem.dylib. // - // Note that System.framework is just a deprecated wrapper over the - // dynamic library. + // Note: Don't get confused by the presence of `System.framework`, + // it is a deprecated wrapper over the dynamic library, so we'd + // rather use the latter. println!("cargo:rustc-link-lib=dylib=System"); // Alternative: Only link to libsystem_blocks.dylib // println!("cargo:rustc-link-search=native=/usr/lib/system"); diff --git a/crates/block-sys/src/lib.rs b/crates/block-sys/src/lib.rs index e3e481b4e..61b605bd3 100644 --- a/crates/block-sys/src/lib.rs +++ b/crates/block-sys/src/lib.rs @@ -284,7 +284,8 @@ pub struct Block_layout { /// } /// ``` /// - /// But it is safe to access this through just `Block_descriptor_header`. + /// But since all of these start with `Block_descriptor_header`, it is + /// always safe to reinterpret this pointer as that. // Note: Important to use `*const c_void` until we know which type it is! pub descriptor: *const c_void, } diff --git a/crates/block2/README.md b/crates/block2/README.md index 1f6f823f1..a448079ee 100644 --- a/crates/block2/README.md +++ b/crates/block2/README.md @@ -7,8 +7,8 @@ Apple's C language extension of blocks in Rust. -This crate provides functionality for interracting with C blocks, which is -effectively the C-equivalent of Rust's closures. +This crate provides functionality for interracting with C blocks, which is the +C-equivalent of Rust's closures. They are _technically_ not limited to only being used in Objective-C, though in practice it's likely the only place you'll ever encounter them. diff --git a/crates/block2/src/block.rs b/crates/block2/src/block.rs index 2b43d77af..892c0e88b 100644 --- a/crates/block2/src/block.rs +++ b/crates/block2/src/block.rs @@ -90,9 +90,9 @@ block_args_impl!( #[repr(C)] pub struct Block { _inner: [u8; 0], - // We effectively store `Block_layout` + a bit more, but `Block` has to - // remain an empty type otherwise the compiler thinks we only have - // provenance over `Block_layout`. + // We store `Block_layout` + a bit more, but `Block` has to remain an + // empty type otherwise the compiler thinks we only have provenance over + // `Block_layout`. _layout: PhantomData, // To get correct variance on args and return types _p: PhantomData R>, diff --git a/crates/block2/src/global.rs b/crates/block2/src/global.rs index 57e885111..3851e045c 100644 --- a/crates/block2/src/global.rs +++ b/crates/block2/src/global.rs @@ -18,7 +18,7 @@ const GLOBAL_DESCRIPTOR: ffi::Block_descriptor_header = ffi::Block_descriptor_he /// An Objective-C block that does not capture its environment. /// -/// This is effectively just a glorified function pointer, and can created and +/// This is effectively a glorified function pointer, and can created and /// stored in static memory using the [`global_block!`] macro. /// /// If [`ConcreteBlock`] is the [`Fn`]-block equivalent, this is likewise the diff --git a/crates/block2/src/lib.rs b/crates/block2/src/lib.rs index 2d0691101..b6634c2ca 100644 --- a/crates/block2/src/lib.rs +++ b/crates/block2/src/lib.rs @@ -1,7 +1,7 @@ //! # Apple's C language extension of blocks //! -//! C Blocks are effectively the C-equivalent of Rust's closures, in that they -//! have the ability to capture their environments. +//! C Blocks are the C-equivalent of Rust's closures, in that they have the +//! ability to capture their environments. //! //! This crate provides capabilities to create and invoke these blocks, in an //! ergonomic "Rust-centric" fashion. diff --git a/crates/header-translator/README.md b/crates/header-translator/README.md index 4f0791944..7518696ae 100644 --- a/crates/header-translator/README.md +++ b/crates/header-translator/README.md @@ -11,7 +11,7 @@ cargo run --bin header-translator Make sure you have the same XCode version installed as the one documented in [`crates/icrate/README.md`](../icrate/README.md). -If you use a different operating system than macOS, or simply have multiple SDKs installed, you can specify the directory as the first argument: +If you use a different operating system than macOS, or have multiple SDKs installed, you can specify the directory as the first argument: ```console cargo run --bin header-translator -- /Applications/Xcode_new.app/Contents/Developer diff --git a/crates/header-translator/src/data/CoreAnimation.rs b/crates/header-translator/src/data/CoreAnimation.rs index f714b2f7e..183236cd7 100644 --- a/crates/header-translator/src/data/CoreAnimation.rs +++ b/crates/header-translator/src/data/CoreAnimation.rs @@ -48,8 +48,8 @@ data! { // `nil` superlayer. // If the layer already has a superlayer, it will be changed - // appropriately by these methods (effectively, removeFromSuperlayer - // is called on the given layer inside these). + // appropriately by these methods (`removeFromSuperlayer` is called on + // the given layer inside these). unsafe -addSublayer; unsafe -insertSublayer_atIndex; unsafe -insertSublayer_below; @@ -193,8 +193,7 @@ data! { unsafe -endFrame; } - // SAFETY: CATransaction is basically just a way to call methods that - // access thread-local state. + // SAFETY: CATransaction methods access thread-local state. class CATransaction { unsafe +begin; unsafe +commit; diff --git a/crates/header-translator/src/method.rs b/crates/header-translator/src/method.rs index 78d7ddfd1..55427b43d 100644 --- a/crates/header-translator/src/method.rs +++ b/crates/header-translator/src/method.rs @@ -170,7 +170,7 @@ impl MemoryManagement { // And if: // > its signature obeys the added restrictions of the method family. // - // Which is just: + // Which is: // > must return a retainable object pointer if result_type.is_id() { // We also check that the correct modifier flags were set for the diff --git a/crates/header-translator/src/rust_type.rs b/crates/header-translator/src/rust_type.rs index 43465bdde..692be0ac8 100644 --- a/crates/header-translator/src/rust_type.rs +++ b/crates/header-translator/src/rust_type.rs @@ -90,7 +90,7 @@ impl AttributeParser<'_, '_> { if position.strip(self.expected_name, needle).is_some() { let rest = rest.trim(); // If it can be stripped from both `name` and `expected_name`, - // it might just appear twice in `name`. + // it might appear twice in `name`. // // This is done to support: // "const char * _Nonnull _Nonnull[]". diff --git a/crates/header-translator/src/stmt.rs b/crates/header-translator/src/stmt.rs index b98f1a962..7e086593e 100644 --- a/crates/header-translator/src/stmt.rs +++ b/crates/header-translator/src/stmt.rs @@ -1467,8 +1467,8 @@ impl fmt::Display for Stmt { // Copying collections is done as a shallow copy: // // - // E.g. it simply does a retain count bump, and hence - // does not require the inner type to implement + // E.g. it does a retain count bump on the items, and + // hence does not require the inner type to implement // `NSCopying`. // // The types does have to be cloneable, since generic @@ -1712,8 +1712,7 @@ impl fmt::Display for Stmt { writeln!(f, "typed_extensible_enum!(pub type {} = {ty};);", id.name)?; } None | Some(UnexposedAttr::BridgedTypedef) => { - // "bridged" typedefs should just use a normal type - // alias. + // "bridged" typedefs should use a normal type alias. writeln!(f, "pub type {} = {ty};", id.name)?; } kind => panic!("invalid alias kind {kind:?} for {ty:?}"), diff --git a/crates/header-translator/translation-config.toml b/crates/header-translator/translation-config.toml index 569d9ced2..f79202ad0 100644 --- a/crates/header-translator/translation-config.toml +++ b/crates/header-translator/translation-config.toml @@ -421,7 +421,7 @@ ios = "16.0" ### - `ns_returns_retained` / `cf_returns_retained` / `os_returns_retained` ### ### The rest are only very rarely used in Apple's frameworks, so while we -### _could_ handle them too, I think it's easier to just do it manually. +### _could_ handle them too, I think it's easier to do it manually. ### ### See https://clang.llvm.org/docs/AttributeReference.html ### @@ -783,7 +783,7 @@ skipped = true skipped = true # The original superclass typedef is a bit difficult to extract from the -# superclass name, so let's just overwrite it. +# superclass name, so let's do it manually. [class.ASCredentialProviderViewController] definition-skipped = true [class.ASAccountAuthenticationModificationViewController] diff --git a/crates/icrate/CHANGELOG.md b/crates/icrate/CHANGELOG.md index b447fc469..f50467e53 100644 --- a/crates/icrate/CHANGELOG.md +++ b/crates/icrate/CHANGELOG.md @@ -269,8 +269,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added `NSTimeInterval`. * Added `NSString::len_utf16` and `NSAttributedString::len_utf16`. * Added `NSString::concat` and `NSString::join_path`. -* Added `CGSize`, `CGPoint` and `CGRect` (just aliases to equivalent - `NS`-types, but helps readability). +* Added `CGSize`, `CGPoint` and `CGRect` (aliases to equivalent `NS`-types + that helps readability). ### Changed * **BREAKING**: `NSSize::new` no longer requires it's arguments to be @@ -310,8 +310,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Removed * `NSObject::hash_code`, `NSObject::is_equal` and `NSObject::description` in - favour of just having the trait implementations `Hash`, `PartiqalEq` and - `Debug`. + favour of having the trait implementations `Hash`, `PartiqalEq` and `Debug`. ## objc2-foundation 0.2.0-alpha.6 - 2022-07-19 @@ -397,7 +396,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Removed * **BREAKING**: Removed `Deref` and `DerefMut` from `NSData` and `NSMutableData`, since these invoke a non-trivial amount of code, and could - easily lead to hard-to-diagnose performance issues. + lead to hard-to-diagnose performance issues. ## objc2-foundation 0.2.0-alpha.3 - 2021-12-22 diff --git a/crates/icrate/examples/basic_usage.rs b/crates/icrate/examples/basic_usage.rs index 21f4fc631..4d841ac9d 100644 --- a/crates/icrate/examples/basic_usage.rs +++ b/crates/icrate/examples/basic_usage.rs @@ -31,7 +31,7 @@ fn main() { autoreleasepool(|pool| { println!("{}", string.as_str(pool)); }); - // Or simply use the `Display` implementation + // Or use the `Display` implementation let _s = string.to_string(); // Using ToString println!("{string}"); // Or Display directly diff --git a/crates/icrate/examples/nspasteboard.rs b/crates/icrate/examples/nspasteboard.rs index b179ef546..a68061935 100644 --- a/crates/icrate/examples/nspasteboard.rs +++ b/crates/icrate/examples/nspasteboard.rs @@ -9,7 +9,7 @@ use objc2::rc::Id; use objc2::runtime::{Class, Object, ProtocolObject}; use objc2::ClassType; -/// Simple, straightforward implementation +/// Simplest implementation pub fn get_text_1(pasteboard: &NSPasteboard) -> Option> { unsafe { pasteboard.stringForType(NSPasteboardTypeString) } } diff --git a/crates/icrate/src/Foundation/__macro_helpers/cached.rs b/crates/icrate/src/Foundation/__macro_helpers/cached.rs index e7002a0d1..5f249a43e 100644 --- a/crates/icrate/src/Foundation/__macro_helpers/cached.rs +++ b/crates/icrate/src/Foundation/__macro_helpers/cached.rs @@ -28,8 +28,7 @@ impl CachedId { let ptr = self.ptr.load(Ordering::SeqCst); // SAFETY: The pointer is either NULL, or has been created below. unsafe { ptr.as_ref() }.unwrap_or_else(|| { - // "Forget" about releasing the object, effectively promoting it - // to a static. + // "Forget" about releasing the object, promoting it to a static. let s = ManuallyDrop::new(f()); let ptr = Id::as_ptr(&s); self.ptr.store(ptr as *mut T, Ordering::SeqCst); diff --git a/crates/icrate/src/Foundation/__macro_helpers/ns_string.rs b/crates/icrate/src/Foundation/__macro_helpers/ns_string.rs index 6a0348ec1..121ee3d74 100644 --- a/crates/icrate/src/Foundation/__macro_helpers/ns_string.rs +++ b/crates/icrate/src/Foundation/__macro_helpers/ns_string.rs @@ -1,7 +1,7 @@ #![cfg(feature = "Foundation_NSString")] //! Macro for making a static NSString. //! -//! This basically does what clang does, see: +//! This closely follows what clang does, see: //! - Apple: //! - GNUStep 2.0 (not yet supported): //! - Other (not yet supported): @@ -39,8 +39,8 @@ extern "C" { #[repr(C)] pub struct CFConstString { isa: &'static Class, - // Important that we don't just use `usize` here, since that would be - // wrong on big-endian systems! + // Important that we don't use `usize` here, since that would be wrong on + // big-endian systems! cfinfo: u32, #[cfg(target_pointer_width = "64")] _rc: u32, diff --git a/crates/icrate/src/Foundation/additions/data.rs b/crates/icrate/src/Foundation/additions/data.rs index 881c68b77..717d1355b 100644 --- a/crates/icrate/src/Foundation/additions/data.rs +++ b/crates/icrate/src/Foundation/additions/data.rs @@ -36,7 +36,7 @@ impl NSData { // bug; it forgets to assign the input buffer and length to the // instance before it swizzles to NSDataWithDeallocatorBlock. // See https://github.com/gnustep/libs-base/pull/213 - // So we just use NSDataWithDeallocatorBlock directly. + // So instead we use NSDataWithDeallocatorBlock directly. // // NSMutableData does not have this problem. #[cfg(feature = "gnustep-1-7")] @@ -112,7 +112,7 @@ impl NSMutableData { #[doc(alias = "replaceBytesInRange:withBytes:length:")] pub fn replace_range(&mut self, range: Range, bytes: &[u8]) { // No need to verify the length of the range here, - // `replaceBytesInRange:` just zero-fills if out of bounds. + // `replaceBytesInRange:` zero-fills if out of bounds. let ptr = bytes.as_ptr() as *mut c_void; unsafe { self.replaceBytesInRange_withBytes_length(range.into(), ptr, bytes.len()) } } diff --git a/crates/icrate/src/Foundation/additions/dictionary.rs b/crates/icrate/src/Foundation/additions/dictionary.rs index 0126319bc..77764f696 100644 --- a/crates/icrate/src/Foundation/additions/dictionary.rs +++ b/crates/icrate/src/Foundation/additions/dictionary.rs @@ -345,7 +345,7 @@ unsafe impl iter::FastEnumerationHelper for NSDictionary #[cfg(feature = "Foundation_NSMutableDictionary")] unsafe impl iter::FastEnumerationHelper for NSMutableDictionary { - // Naturally, the same goes for mutable dictionaries. + // The same goes for mutable dictionaries. type Item = K; #[inline] diff --git a/crates/icrate/src/Foundation/additions/geometry.rs b/crates/icrate/src/Foundation/additions/geometry.rs index 63cdc3f8c..777347928 100644 --- a/crates/icrate/src/Foundation/additions/geometry.rs +++ b/crates/icrate/src/Foundation/additions/geometry.rs @@ -18,11 +18,11 @@ type InnerFloat = f32; // TODO: Use a newtype here? pub type CGFloat = InnerFloat; -// NSGeometry types are just aliases to CGGeometry types on iOS, tvOS, watchOS -// and macOS 64bit (and hence their Objective-C encodings are different). +// NSGeometry types are aliases to CGGeometry types on iOS, tvOS, watchOS and +// macOS 64bit (and hence their Objective-C encodings are different). // // TODO: Adjust `objc2-encode` so that this is handled there, and so that we -// can effectively just forget about it and use `NS` and `CG` types equally. +// can effectively forget about it and use `NS` and `CG` types equally. #[cfg(all( feature = "apple", not(all(target_os = "macos", target_pointer_width = "32")) @@ -346,7 +346,7 @@ impl CGRect { /// A point in a Cartesian coordinate system. /// -/// This is just a convenience alias for [`CGPoint`]. For ease of use, it is +/// This is a convenience alias for [`CGPoint`]. For ease of use, it is /// available on all platforms, though in practice it is only useful on macOS. /// /// See [Apple's documentation](https://developer.apple.com/documentation/foundation/nspoint?language=objc). @@ -354,7 +354,7 @@ pub type NSPoint = CGPoint; /// A two-dimensional size. /// -/// This is just a convenience alias for [`CGSize`]. For ease of use, it is +/// This is a convenience alias for [`CGSize`]. For ease of use, it is /// available on all platforms, though in practice it is only useful on macOS. /// /// See [Apple's documentation](https://developer.apple.com/documentation/foundation/nssize?language=objc). @@ -362,7 +362,7 @@ pub type NSSize = CGSize; /// A rectangle. /// -/// This is just a convenience alias for [`CGRect`]. For ease of use, it is +/// This is a convenience alias for [`CGRect`]. For ease of use, it is /// available on all platforms, though in practice it is only useful on macOS. /// /// See [Apple's documentation](https://developer.apple.com/documentation/foundation/nsrect?language=objc). @@ -406,7 +406,7 @@ mod tests { use crate::Foundation::{NSEqualPoints, NSEqualRects, NSEqualSizes}; // We assume that comparisons handle e.g. `x` and `y` in the same way, - // therefore we just set the coordinates / dimensions to the same. + // therefore we set the coordinates / dimensions to the same. let cases: &[(CGFloat, CGFloat)] = &[ (0.0, 0.0), (-0.0, -0.0), diff --git a/crates/icrate/src/Foundation/additions/iter.rs b/crates/icrate/src/Foundation/additions/iter.rs index 5358cd4fe..7d59a91b4 100644 --- a/crates/icrate/src/Foundation/additions/iter.rs +++ b/crates/icrate/src/Foundation/additions/iter.rs @@ -174,7 +174,7 @@ impl FastEnumeratorHelper { // violated, but if that is the case, the program already // has UB, so then it is better that we detect it. // - // - The value is a simple integer, so is always initialized. + // - The value is an integer, so is always initialized. // // // We do an unaligned read here since we have no guarantees diff --git a/crates/icrate/src/Foundation/additions/number.rs b/crates/icrate/src/Foundation/additions/number.rs index ac99d430e..386239da4 100644 --- a/crates/icrate/src/Foundation/additions/number.rs +++ b/crates/icrate/src/Foundation/additions/number.rs @@ -20,8 +20,8 @@ use objc2::encode::Encoding; use crate::common::*; use crate::Foundation::{CGFloat, NSNumber}; -// SAFETY: `NSNumber` is just a wrapper around an integer/float/bool, and it -// is immutable. +// SAFETY: `NSNumber` is a wrapper around an integer/float/bool, and it is +// immutable. unsafe impl Sync for NSNumber {} unsafe impl Send for NSNumber {} diff --git a/crates/icrate/src/Foundation/additions/set.rs b/crates/icrate/src/Foundation/additions/set.rs index 8057d1cf8..a0c5ba528 100644 --- a/crates/icrate/src/Foundation/additions/set.rs +++ b/crates/icrate/src/Foundation/additions/set.rs @@ -116,7 +116,8 @@ impl NSSet { T: IsIdCloneable, { // SAFETY: The `T: IsIdCloneable` bound ensures that it is safe to - // create what is effectively a copy from an `&self` reference. + // create what is effectively a copy of the collection from a `&self` + // reference. // // Could be implemented as: // NSArray::from_vec(self.to_vec_retained()) diff --git a/crates/icrate/src/Foundation/additions/thread.rs b/crates/icrate/src/Foundation/additions/thread.rs index 7aa3ffaba..68a3c62ab 100644 --- a/crates/icrate/src/Foundation/additions/thread.rs +++ b/crates/icrate/src/Foundation/additions/thread.rs @@ -154,8 +154,7 @@ impl MainThreadMarker { /// Submit the given closure to the runloop on the main thread. /// - /// If the current thread is the main thread, this simply runs the - /// closure. + /// If the current thread is the main thread, this runs the closure. /// /// The closure is passed a [`MainThreadMarker`] that it can further use /// to access APIs that are only accessible from the main thread. @@ -239,7 +238,7 @@ impl Drop for MainThreadBound { fn drop(&mut self) { if mem::needs_drop::() { // TODO: Figure out whether we should assume the main thread to be - // dead if we're panicking, and just leak instead? + // dead if we're panicking, and leak instead? MainThreadMarker::run_on_main(|_mtm| { let this = self; // SAFETY: The value is dropped on the main thread, which is diff --git a/crates/icrate/src/Foundation/additions/value.rs b/crates/icrate/src/Foundation/additions/value.rs index 5a312b70e..78a69358d 100644 --- a/crates/icrate/src/Foundation/additions/value.rs +++ b/crates/icrate/src/Foundation/additions/value.rs @@ -61,7 +61,7 @@ impl NSValue { /// The type of `T` must be what the NSValue actually stores, and any /// safety invariants that the value has must be upheld. /// - /// Note that it may be, but is not always, enough to simply check whether + /// Note that it may be enough, although is not always, to check whether /// [`contains_encoding`] returns `true`. For example, `NonNull` have /// the same encoding as `*const T`, but `NonNull` is clearly not /// safe to return from this function even if you've checked the encoding diff --git a/crates/icrate/src/Foundation/fixes/generics.rs b/crates/icrate/src/Foundation/fixes/generics.rs index 686e3d893..458c27300 100644 --- a/crates/icrate/src/Foundation/fixes/generics.rs +++ b/crates/icrate/src/Foundation/fixes/generics.rs @@ -78,7 +78,7 @@ __inner_extern_class!( /// /// But since we already require `T: IsCloneable` on `NSCopying`, and /// already prevent other forms of `&NSArray -> Id>`, - /// this is actually just fine, since `Id>: Send | Sync` + /// this is actually fine, since `Id>: Send | Sync` /// requires `NSArray: Send + Sync` (and hence `T: Send + Sync`). __inner: PhantomData>, } @@ -128,7 +128,7 @@ __inner_extern_class!( pub struct NSDictionary { // SAFETY: Auto traits specified below. __superclass: UnsafeIgnoreAutoTraits, - // Same as if the dictionary was just: + // Same as if the dictionary was implemented with: // `(NSArray, NSArray)` __inner: PhantomData<(Id, Id)>, } @@ -180,7 +180,7 @@ __inner_extern_class!( pub struct NSSet { // SAFETY: Auto traits specified below. __superclass: UnsafeIgnoreAutoTraits, - // Same as if the set was just `NSArray`. + // Same as if the set was implemented as `NSArray`. __inner: PhantomData>, } @@ -253,7 +253,7 @@ __inner_extern_class!( pub struct NSOrderedSet { // SAFETY: Auto traits specified below. __superclass: UnsafeIgnoreAutoTraits, - // Same as if the set was just `NSArray`. + // Same as if the set was implemented with `NSArray`. __inner: PhantomData>, } @@ -302,7 +302,7 @@ __inner_extern_class!( pub struct NSEnumerator { // SAFETY: Auto traits specified below. __superclass: UnsafeIgnoreAutoTraits, - // Enumerators are basically the same as if we were just storing + // Enumerators are basically the same as if we were storing // `NSMutableArray`, and removed an element from that on // each iteration. // diff --git a/crates/icrate/src/Foundation/macros/ns_string.rs b/crates/icrate/src/Foundation/macros/ns_string.rs index 58b4ea1c5..b122ad43f 100644 --- a/crates/icrate/src/Foundation/macros/ns_string.rs +++ b/crates/icrate/src/Foundation/macros/ns_string.rs @@ -90,8 +90,8 @@ macro_rules! __ns_string_inner { // Note: We create both the ASCII + NUL and the UTF-16 + NUL versions // of the string, since we can't conditionally create a static. // - // Since we don't add the `#[used]` attribute, Rust can fairly easily - // figure out that one of the variants are never used, and simply + // Since we don't add the `#[used]` attribute, Rust can fairly + // reliably figure out that one of the variants are never used, and // exclude it. // Convert the input slice to a C-style string with a NUL byte. diff --git a/crates/icrate/tests/auto_traits.rs b/crates/icrate/tests/auto_traits.rs index 015719bcd..132539402 100644 --- a/crates/icrate/tests/auto_traits.rs +++ b/crates/icrate/tests/auto_traits.rs @@ -21,8 +21,8 @@ use objc2::{declare_class, ClassType}; // that is the entire idea of `UnwindSafe` (that if the object could have // been mutated, it is not exception safe). // -// Also note that this is still just a speed bump, not actually part of -// any unsafe contract; we can't really protect against it if something is not +// Also note that this is still only a speed bump, not actually part of any +// unsafe contract; we can't really protect against it if something is not // exception safe, since `UnwindSafe` is a safe trait. fn assert_unwindsafe() {} diff --git a/crates/objc-sys/CHANGELOG.md b/crates/objc-sys/CHANGELOG.md index ae303f0c3..50be09ee3 100644 --- a/crates/objc-sys/CHANGELOG.md +++ b/crates/objc-sys/CHANGELOG.md @@ -48,8 +48,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Removed * **BREAKING**: Removed type aliases `Class`, `Ivar`, `Method` and `Protocol` - since they could easily be mistaken for the `objc2::runtime` structs with - the same name. + since they could be mistaken for the `objc2::runtime` structs with the same + name. * **BREAKING**: Removed `objc_property_t`. * **BREAKING**: Removed `objc_hook_getClass` and `objc_hook_lazyClassNamer` type aliases (for now). diff --git a/crates/objc-sys/README.md b/crates/objc-sys/README.md index 99a76bb67..2b5c94d4d 100644 --- a/crates/objc-sys/README.md +++ b/crates/objc-sys/README.md @@ -19,8 +19,8 @@ Apple's runtime, but if you're using another runtime you must tell it to this library using feature flags (you might have to disable the default `apple` feature first). -One could ask, why even bother supporting other runtimes? To that, there's a -simple answer: _Robustness_. By testing with these alternative runtimes in CI, +One could ask, why even bother supporting other runtimes? For me, the primary +reasoning iss _robustness_. By testing with these alternative runtimes in CI, we become by extension much more confident that our implementation doesn't rely on brittle unspecified behaviour, and works across different macOS and iOS versions. @@ -30,8 +30,8 @@ iOS versions. - Feature flag: `apple`. -This is used by default, and naturally has the highest support priority (e.g. -all of `objc2`/`icrate` will work with this runtime). +This is used by default, and has the highest support priority (all of +`objc2`/`icrate` will work with this runtime). The supported runtime version (higher versions lets the compiler enable newer optimizations, at the cost of not supporting older operating systems) can be @@ -67,8 +67,8 @@ The default versions are the [same as those Rust itself has][rust-apple-spec]. **Unstable: Hasn't been tested on Windows yet!** -This is essentially just [a fork](https://github.com/microsoft/libobjc2) based -on GNUStep's `libobjc2` version 1.8, with very few user-facing changes. +[A fork](https://github.com/microsoft/libobjc2) based on GNUStep's `libobjc2` +version 1.8, with very few user-facing changes. ### [`ObjFW`](https://github.com/ObjFW/ObjFW) @@ -86,9 +86,9 @@ This library will probably only ever support ["Modern"][modern] Objective-C runtimes, since support for reference-counting primitives like `objc_retain` and `objc_autoreleasePoolPop` is a vital requirement for most applications. -Just so we're being clear, this rules out the GCC [`libobjc`][gcc-libobjc] -runtime (see [this][gcc-objc-support]), the [`mulle-objc`] runtime and -[cocotron]. (But support for [`darling`] may be added). +This rules out the GCC [`libobjc`][gcc-libobjc] runtime (see +[this][gcc-objc-support]), the [`mulle-objc`] runtime and [cocotron]. (But +support for [`darling`] may be added). More information on different runtimes can be found in GNUStep's [Objective-C Compiler and Runtime FAQ][gnustep-faq]. diff --git a/crates/objc-sys/build.rs b/crates/objc-sys/build.rs index 2494b5da6..a45244219 100644 --- a/crates/objc-sys/build.rs +++ b/crates/objc-sys/build.rs @@ -185,7 +185,7 @@ fn main() { // Default in clang is 1.6 // GNUStep's own default is 1.8 GNUStep(major, minor) => format!("gnustep-{major}.{minor}"), - // WinObjC's libobjc2 is just a fork of gnustep's from version 1.8 + // WinObjC's libobjc2 is a fork of gnustep's from version 1.8 WinObjC => "gnustep-1.8".into(), ObjFW(version) => { // Default in clang diff --git a/crates/objc-sys/src/class.rs b/crates/objc-sys/src/class.rs index 0a1027ad5..207c2a4c1 100644 --- a/crates/objc-sys/src/class.rs +++ b/crates/objc-sys/src/class.rs @@ -19,7 +19,7 @@ pub struct objc_class { /// The pointer represents opaque data, and is definitely not just an integer, /// so its signedness (i8 vs. u8) is not applicable. /// -/// So we just assign it here as a private alias to u8, to not document the +/// So we assign it here as a private alias to u8, to not document the /// difference. type ivar_layout_type = u8; diff --git a/crates/objc-sys/src/image_info.rs b/crates/objc-sys/src/image_info.rs index a05020100..9c9333322 100644 --- a/crates/objc-sys/src/image_info.rs +++ b/crates/objc-sys/src/image_info.rs @@ -38,7 +38,7 @@ impl __ImageInfo { #[inline] pub const fn system() -> Self { // We don't currently do anything relating to class properties, but - // let's just mimic what Clang does! + // let's mimic what Clang does! let mut flags = Self::CLASS_PROPERTIES; if cfg!(target_simulator) { diff --git a/crates/objc-sys/src/protocol.rs b/crates/objc-sys/src/protocol.rs index 47cb77d68..071f4e664 100644 --- a/crates/objc-sys/src/protocol.rs +++ b/crates/objc-sys/src/protocol.rs @@ -11,8 +11,8 @@ use crate::{OpaqueData, BOOL}; /// Note that, although protocols are objects, sending messages to them is /// deprecated and may not work in the future. /// -/// The naming of this follows GNUStep; this does not exist in Apple's -/// original, there `Protocol` is just a type alias of `objc_object`. +/// The naming of this follows GNUStep; this struct does not exist in Apple's +/// runtime, there `Protocol` is a type alias of `objc_object`. #[repr(C)] pub struct objc_protocol { _priv: [u8; 0], diff --git a/crates/objc-sys/src/types.rs b/crates/objc-sys/src/types.rs index c0bcc7a22..b4206bc74 100644 --- a/crates/objc-sys/src/types.rs +++ b/crates/objc-sys/src/types.rs @@ -61,8 +61,8 @@ mod inner { // This has changed since v0.90, but we don't support that yet. pub(crate) type BOOL = i8; - // Note that ObjFW uses `bool` in return types, but that doesn't change - // the ABI, so we'll just use `BOOL` there for ease of use. + // Note that ObjFW usually uses `bool` in return types, but that doesn't + // change the ABI, so we'll use `BOOL` there as well, for ease of use. } /// The Objective-C `BOOL` type. diff --git a/crates/objc2-encode/src/encoding.rs b/crates/objc2-encode/src/encoding.rs index 41e595a7d..e7917c046 100644 --- a/crates/objc2-encode/src/encoding.rs +++ b/crates/objc2-encode/src/encoding.rs @@ -145,9 +145,9 @@ impl Encoding { /// The encoding of [`c_long`](`std::os::raw::c_long`) on the current /// target. /// - /// Ideally the encoding of `long` would just be the same as `int` when - /// it's 32 bits wide and the same as `long long` when it is 64 bits wide; - /// then `c_long::ENCODING` would just work. + /// Ideally the encoding of `long` would be the same as `int` when it's 32 + /// bits wide and the same as `long long` when it is 64 bits wide; then + /// `c_long::ENCODING` would just work. /// /// Unfortunately, `long` have a different encoding than `int` when it is /// 32 bits wide; the [`l`][`Encoding::Long`] encoding. diff --git a/crates/objc2-encode/src/helper.rs b/crates/objc2-encode/src/helper.rs index 7901a2929..aa0a09258 100644 --- a/crates/objc2-encode/src/helper.rs +++ b/crates/objc2-encode/src/helper.rs @@ -120,8 +120,8 @@ pub(crate) fn compare_encodings( true } // A bit unsure about this one, but the "safe" default - // here is just to say that one container with items do - // not compare equal to another container without items. + // here is to say that a container with items does not + // compare equal to another container without items. // // Note that this may be confusing, since a `Pointer` to // the two containers might suddenly start comparing diff --git a/crates/objc2-encode/src/lib.rs b/crates/objc2-encode/src/lib.rs index 8ca9b658c..eebc2fa00 100644 --- a/crates/objc2-encode/src/lib.rs +++ b/crates/objc2-encode/src/lib.rs @@ -8,7 +8,7 @@ //! it can be parsed from an encoding at runtime. //! //! The types from this crate is exported under the [`objc2`] crate as -//! `objc2::encode`, so usually you would just use it from there. +//! `objc2::encode`, so usually you would use it from there. //! //! [`objc2`]: https://crates.io/crates/objc2 //! diff --git a/crates/objc2/CHANGELOG.md b/crates/objc2/CHANGELOG.md index 4da140bf8..824b6c550 100644 --- a/crates/objc2/CHANGELOG.md +++ b/crates/objc2/CHANGELOG.md @@ -75,8 +75,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Fixed memory leaks in and improved performance of `exception::catch`. ### Removed -* **BREAKING**: Removed `rc::SliceId`, since it is trivially implementable - outside `objc2` from the layout guarantees of `rc::Id`. +* **BREAKING**: Removed `rc::SliceId`, since it is implementable outside + `objc2` from the layout guarantees of `rc::Id`. * **BREAKING**: Removed `Ownership` type parameter from `Id`, as well as `rc::Ownership`, `rc::Owned`, `rc::Shared`, `Id::from_shared` and `Id::into_shared`. This functionality has been moved from being at the @@ -104,8 +104,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). let obj: Id = unsafe { msg_send_id![NSObject::class(), new] }; ``` * **BREAKING**: Removed `impl TryFrom> for Id` impl since it - did not have a proper error type, making it less useful than just using - `WeakId::load`. + did not have a proper error type, making it less useful than `WeakId::load`. * **BREAKING**: Removed forwarding `Iterator` implementation for `Id`, since it conflicts with the `IntoIterator` implementation that it now has instead. @@ -117,7 +116,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * Added support for selectors with multiple colons like `abc::` in the `sel!`, `extern_class!`, `extern_protocol!` and `declare_class!` macros. * Added ability to use `#[method_id(mySelector:)]` inside `declare_class!`, - just like you would do in `extern_methods!`. + like you would do in `extern_methods!`. * Added 16-fold impls for `EncodeArguments`, `MessageArguments`, and `MethodImplementation`. * Added `NSObjectProtocol` trait for allowing `ProtocolObject` to implement `Debug`, `Hash`, `PartialEq` and `Eq`. @@ -135,7 +134,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). `#[method(myMethod:error:_)]` instead of `#[method(myMethod:error:)]`). * **BREAKING**: Fundamentally changed how protocols work. Instead of being structs with inherent methods, they're now traits. This means that you can - use their methods much more naturally from your Objective-C objects. + use their methods more naturally from your Objective-C objects. An example: ```rust @@ -362,8 +361,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). * **BREAKING**: Change syntax in `declare_class!` macro to be more Rust-like. * **BREAKING**: Renamed `Id::from_owned` to `Id::into_shared`. * **BREAKING**: The return type of `msg_send_id!` is now more generic; it can - now either be `Option>` or `Id<_, _>` (if the latter, it'll simply - panic). + now either be `Option>` or `Id<_, _>` (if the latter, it'll panic + if the method returned `NULL`). Example: ```rust @@ -493,8 +492,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). = note: ...but `MethodImplementation` is actually implemented for the type `extern "C" fn(&'0 mut Object, Sel) -> *mut Object`, for some specific lifetime `'0` ``` - Fret not, the fix is easy! Just let the compiler infer the argument and - return types: + To fix this, let the compiler infer the argument and return types: ```rust // After let init: extern "C" fn(_, _) -> _ = init; @@ -666,8 +664,8 @@ Note: To use this version, specify `objc2-encode = "=2.0.0-beta.0"` in your extra functionality on `rc::Id`. ### Changed -* **BREAKING**: The `exception` feature now just enables the `exception` - module for general use. Use the new `catch_all` feature to wrap all message +* **BREAKING**: The `exception` feature now only enables the `exception` + module, for general use. Use the new `catch_all` feature to wrap all message sends in a `@try/@catch`. * **BREAKING**: Updated `objc-sys` to `v0.1.0`. * **BREAKING**: Updated `objc2-encode` (`Encoding`, `Encode`, `RefEncode` and @@ -743,13 +741,13 @@ Note: To use this version, specify `objc2-encode = "=2.0.0-alpha.1"` in your `INSString::as_str` so that it knows which lifetime to bound the returned `&str` with. - Simple migration: ```rust - // Change + // Before autoreleasepool(|| { // Some code that autoreleases objects }); - // To + + // After autoreleasepool(|_pool| { // Some code that autoreleases objects }); diff --git a/crates/objc2/examples/encode_nsuinteger.rs b/crates/objc2/examples/encode_nsuinteger.rs index d48964cdc..7983fa11b 100644 --- a/crates/objc2/examples/encode_nsuinteger.rs +++ b/crates/objc2/examples/encode_nsuinteger.rs @@ -1,7 +1,7 @@ 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`. +// Note: In this case `NSUInteger` could be a type alias for `usize`, and +// actually that's already available as `objc2::ffi::NSUInteger`. #[repr(transparent)] struct NSUInteger { _inner: usize, diff --git a/crates/objc2/src/__macro_helpers/declare_class.rs b/crates/objc2/src/__macro_helpers/declare_class.rs index 371fb63c4..274fc981b 100644 --- a/crates/objc2/src/__macro_helpers/declare_class.rs +++ b/crates/objc2/src/__macro_helpers/declare_class.rs @@ -8,7 +8,7 @@ use crate::{ClassType, Message, MessageReceiver}; use super::{CopyOrMutCopy, Init, MaybeUnwrap, New, Other}; use crate::mutability; -// One could imagine a different design where we simply had a method like +// One could imagine a different design where we had a method like // `fn convert_receiver()`, but that won't work in `declare_class!` since we // can't actually modify the `self` argument (e.g. `let self = foo(self)` is // not allowed). diff --git a/crates/objc2/src/class_type.rs b/crates/objc2/src/class_type.rs index e15c04cd4..aeb7b216d 100644 --- a/crates/objc2/src/class_type.rs +++ b/crates/objc2/src/class_type.rs @@ -49,7 +49,7 @@ use crate::Message; /// /// // Get the class of the object. /// let cls = ::class(); -/// // Or, since the trait is in scope, just: +/// // Or, since the trait is in scope. /// let cls = MyObject::class(); /// /// // We can now access properties of the class. @@ -78,8 +78,8 @@ use crate::Message; /// let obj: Id = unsafe { msg_send_id![obj, init] }; /// ``` /// -/// Use the [`extern_class!`][crate::extern_class] macro to easily implement -/// this trait for a type. +/// Use the [`extern_class!`][crate::extern_class] macro to implement this +/// trait for a type. /// /// ``` /// use objc2::runtime::NSObject; @@ -127,8 +127,7 @@ pub unsafe trait ClassType: Message { /// The name of the Objective-C class that this type represents. /// - /// `T::NAME` is essentially just the `const` version of - /// `T::class().name()`. + /// `T::NAME` is the `const` version of `T::class().name()`. const NAME: &'static str; /// Get a reference to the Objective-C class that this type represents. @@ -191,9 +190,8 @@ pub unsafe trait ClassType: Message { // - The object is known to not be mutable (or have a mutable // subclass) due to the `IsRetainable` bound. // - The pointer is valid since it came from `&self`. - // - The lifetime of the pointer itself is, naturally, extended, - // but any lifetime that the object may carry is still kept within - // the type itself. + // - The lifetime of the pointer itself is extended, but any lifetime + // that the object may carry is still kept within the type itself. let obj = unsafe { Id::retain(ptr) }; // SAFETY: The pointer came from `&self`, which is always non-null // (and objc_retain always returns the same value). diff --git a/crates/objc2/src/declare/declare_class_tests.rs b/crates/objc2/src/declare/declare_class_tests.rs index e4932ad87..50144e22c 100644 --- a/crates/objc2/src/declare/declare_class_tests.rs +++ b/crates/objc2/src/declare/declare_class_tests.rs @@ -39,8 +39,8 @@ fn test_deprecated() { // Test that `cfg` works properly. // -// We use `debug_assertions` here just because it's something that we know -// our CI already tests. +// We use `debug_assertions` here because it's something that we know our CI +// already tests. declare_class!( struct DeclareClassCfg; @@ -428,7 +428,7 @@ fn test_subclass_duplicate_ivar() { let _ = SubCls::class(); - // The rest is just to show what would go wrong if it didn't panic + // The rest is to show what would go wrong if it didn't panic assert_eq!(Cls::class().instance_size(), 16); assert_eq!(SubCls::class().instance_size(), 16); diff --git a/crates/objc2/src/declare/ivar.rs b/crates/objc2/src/declare/ivar.rs index 897630328..65410d8e7 100644 --- a/crates/objc2/src/declare/ivar.rs +++ b/crates/objc2/src/declare/ivar.rs @@ -192,8 +192,8 @@ impl Drop for Ivar { impl Ivar { /// Get a pointer to the instance variable. /// - /// Note that if the ivar has already been initialized, you can simply - /// use the `Deref` implementation to get a reference. + /// Note that if the ivar has already been initialized, you can use the + /// `Deref` implementation to get a reference. /// /// This is similar to [`MaybeUninit::as_ptr`], see that for usage /// instructions. @@ -225,8 +225,8 @@ impl Ivar { /// This is useful when you want to initialize the ivar inside an `init` /// method (where it may otherwise not have been safely initialized yet). /// - /// Note that if the ivar has already been initialized, you can simply - /// use the `DerefMut` implementation to get a mutable reference. + /// Note that if the ivar has already been initialized, you can use the + /// `DerefMut` implementation to get a mutable reference. /// /// This is similar to [`MaybeUninit::as_mut_ptr`], see that for usage /// instructions. diff --git a/crates/objc2/src/declare/ivar_encode.rs b/crates/objc2/src/declare/ivar_encode.rs index d2302cfe9..2ff363fe9 100644 --- a/crates/objc2/src/declare/ivar_encode.rs +++ b/crates/objc2/src/declare/ivar_encode.rs @@ -54,7 +54,7 @@ mod tests { assert!(!mem::needs_drop::>()); assert!(!mem::needs_drop::>()); - // You wouldn't do this, but just as a check + // You wouldn't do this, but let's make sure it works as expected #[repr(transparent)] struct DropAndEncode(i32); diff --git a/crates/objc2/src/declare/mod.rs b/crates/objc2/src/declare/mod.rs index 66a1322b7..71e6ec54e 100644 --- a/crates/objc2/src/declare/mod.rs +++ b/crates/objc2/src/declare/mod.rs @@ -529,8 +529,9 @@ impl ClassBuilder { // `class_addIvar` sadly doesn't check this for us. // // We must _always_ do the check, since there is no way for the user - // to know if the superclass has a declared instance variable on it - // (e.g. we can't just make `add_ivar` unsafe). + // to statically know if the superclass has a declared instance + // variable on it, since that may change if a new version of the + // library/framework the class came from is released. if let Some(_ivar) = self .superclass() .and_then(|superclass| superclass.instance_variable(name)) diff --git a/crates/objc2/src/encode/__unstable.rs b/crates/objc2/src/encode/__unstable.rs index 9f1a1e4ba..90f89b405 100644 --- a/crates/objc2/src/encode/__unstable.rs +++ b/crates/objc2/src/encode/__unstable.rs @@ -61,7 +61,7 @@ impl convert_private::Sealed for Option<&mut Id> {} impl convert_private::Sealed for &mut Option> {} impl convert_private::Sealed for Option<&mut Option>> {} -/// Represents types that can easily be converted to/from an [`Encode`] type. +/// Represents types that can be converted to/from an [`Encode`] type. /// /// This is implemented specially for [`bool`] to allow using that as /// Objective-C `BOOL`, where it would otherwise not be allowed (since they diff --git a/crates/objc2/src/encode/mod.rs b/crates/objc2/src/encode/mod.rs index ddbdc63a3..4cdf1d46c 100644 --- a/crates/objc2/src/encode/mod.rs +++ b/crates/objc2/src/encode/mod.rs @@ -291,7 +291,7 @@ unsafe impl RefEncode for Option { // TODO: Implement for `PhantomData` and `PhantomPinned`? -/// Simple helper for implementing [`Encode`]. +/// Helper for implementing [`Encode`]. macro_rules! encode_impls { ($($t:ty => $e:ident,)*) => ($( unsafe impl Encode for $t { @@ -337,7 +337,7 @@ encode_impls_size!( usize => (u16, u32, u64), ); -/// Simple helper for implementing [`RefEncode`]. +/// Helper for implementing [`RefEncode`]. macro_rules! pointer_refencode_impl { ($($t:ty),*) => ($( unsafe impl RefEncode for $t { @@ -358,7 +358,7 @@ unsafe impl RefEncode for u8 { const ENCODING_REF: Encoding = Encoding::String; } -/// Simple helper for implementing [`Encode`] for nonzero integer types. +/// Helper for implementing [`Encode`] for nonzero integer types. macro_rules! encode_impls_nonzero { ($($nonzero:ident => $type:ty,)*) => ($( unsafe impl Encode for $nonzero { @@ -387,7 +387,7 @@ encode_impls_nonzero!( NonZeroUsize => usize, ); -/// Simple helper for implementing for atomic types. +/// Helper for implementing for atomic types. macro_rules! encode_atomic_impls { ($( $(#[$m:meta])* diff --git a/crates/objc2/src/lib.rs b/crates/objc2/src/lib.rs index 595a99d5c..63b61b113 100644 --- a/crates/objc2/src/lib.rs +++ b/crates/objc2/src/lib.rs @@ -3,7 +3,7 @@ //! Objective-C was the standard programming language on Apple platforms like //! macOS, iOS, iPadOS, tvOS and watchOS. It is an object-oriented language //! centered around "sending messages" to its instances - this can for the -//! most part be viewed as a simple method call. +//! most part be viewed as a function call. //! //! It has since been superseded by Swift, but most of the core libraries and //! frameworks that are in use on Apple systems are still written in @@ -44,7 +44,7 @@ //! let obj1: Id = unsafe { //! msg_send_id![NSObject::alloc(), init] //! }; -//! // Or we can simply do +//! // Or //! let obj2 = NSObject::new(); //! //! // Usage @@ -64,12 +64,12 @@ //! // Deallocation on drop //! ``` //! -//! Note that this very simple example contains a lot of `unsafe` (which -//! should all ideally be justified with a `// SAFETY` comment). This is -//! required because our compiler can verify very little about the Objective-C -//! invocation, including all argument and return types used in [`msg_send!`]; -//! we could have just as easily accidentally made `hash` an `f32`, or any -//! other type, and this would trigger undefined behaviour! +//! Note that this example contains a lot of `unsafe` (which should all +//! ideally be justified with a `// SAFETY` comment). This is required because +//! our compiler can verify very little about the Objective-C invocation, +//! including all argument and return types used in [`msg_send!`]. We could +//! have accidentally made `hash` an `f32`, or any other type, and this would +//! trigger undefined behaviour! //! //! See the `icrate` crate for much more ergonomic usage of the system //! frameworks like `Foundation`, `AppKit`, `UIKit` and so on. diff --git a/crates/objc2/src/macros/__attribute_helpers.rs b/crates/objc2/src/macros/__attribute_helpers.rs index 3b84d3f72..e8d30e635 100644 --- a/crates/objc2/src/macros/__attribute_helpers.rs +++ b/crates/objc2/src/macros/__attribute_helpers.rs @@ -39,7 +39,7 @@ macro_rules! __extract_and_apply_cfg_attributes { ) @($($output:tt)*) } => { - // Simply ignore the attribute, and continue parsing the rest + // Ignore the attribute, and continue parsing the rest $crate::__extract_and_apply_cfg_attributes! { @($($m_rest)*) @($($output)*) diff --git a/crates/objc2/src/macros/declare_class.rs b/crates/objc2/src/macros/declare_class.rs index d8a611679..16edca8df 100644 --- a/crates/objc2/src/macros/declare_class.rs +++ b/crates/objc2/src/macros/declare_class.rs @@ -164,8 +164,8 @@ /// /// `unsafe impl T { ... }` asserts that the types match those that are /// expected when the method is invoked from Objective-C. Note that unlike -/// with [`extern_methods!`], there are no safe-guards here; you can easily -/// write `i8`, but if Objective-C thinks it's an `u32`, it will cause UB when +/// with [`extern_methods!`], there are no safe-guards here; you can write +/// `i8`, but if Objective-C thinks it's an `u32`, it will cause UB when /// called! /// /// `unsafe impl P for T { ... }` requires that all required methods of the @@ -222,7 +222,7 @@ /// /// // Some types like `u8`, `bool`, `Option>` and /// // `Option>` are safe to zero-initialize, and we can -/// // simply write to the variable as normal: +/// // write to the variable as normal: /// *this.foo = foo; /// *this.bar = 42; /// @@ -339,7 +339,7 @@ /// } /// /// - (uint8_t)foo { -/// return self->foo; // Or just `foo` +/// return self->foo; /// } /// /// - (NSObject*)object { diff --git a/crates/objc2/src/macros/extern_class.rs b/crates/objc2/src/macros/extern_class.rs index 3d6572eef..44534d2fe 100644 --- a/crates/objc2/src/macros/extern_class.rs +++ b/crates/objc2/src/macros/extern_class.rs @@ -48,9 +48,9 @@ /// - The [`Super`] class. /// /// Due to Rust trait limitations, specifying e.g. the superclass `NSData` -/// would not give you easy access to `NSObject`'s functionality. Therefore, -/// you may optionally specify additional parts of the inheritance chain -/// using an `#[inherits(...)]` attribute. +/// would not give you the ability to convert via. `AsRef` to `NSObject`. +/// Therefore, you may optionally specify additional parts of the +/// inheritance chain using an `#[inherits(...)]` attribute. /// - The class' [`Mutability`]. /// - Optionally, the class' [`NAME`] - if not specified, this will default to /// the struct name. @@ -87,8 +87,8 @@ /// /// # Examples /// -/// Create a new type to represent the `NSFormatter` class (of course, we -/// could have just used `icrate::Foundation::NSFormatter`). +/// Create a new type to represent the `NSFormatter` class (for demonstration, +/// `icrate::Foundation::NSFormatter` exist for exactly this purpose). /// /// ``` /// # #[cfg(not_available)] @@ -188,7 +188,7 @@ macro_rules! extern_class { $(const NAME: &'static str = $name_const:expr;)? } ) => { - // Just shorthand syntax for the following + // Shorthand syntax for the following $crate::extern_class!( $(#[$m])* $v struct $name {} @@ -414,9 +414,9 @@ macro_rules! __extern_class_impl_traits { = <$superclass as $crate::RefEncode>::ENCODING_REF; } - // SAFETY: This is essentially just a newtype wrapper over `Object` - // (we even ensure that `Object` is always last in our inheritance - // tree), so it is always safe to reinterpret as that. + // SAFETY: This is a newtype wrapper over `Object` (we even ensure + // that `Object` is always last in our inheritance tree), so it is + // always safe to reinterpret as that. // // That the object must work with standard memory management is // properly upheld by the fact that the superclass is required by @@ -444,9 +444,9 @@ macro_rules! __extern_class_impl_traits { // erasable by e.g. `ClassType::retain` since `NSObject` does not // allow that. // - // Note that you can easily have two different variables pointing to - // the same object, `x: &T` and `y: &T::Target`, and this would be - // perfectly safe! + // Note that you can have two different variables pointing to the same + // object, `x: &T` and `y: &T::Target`, and this would be perfectly + // safe! $(#[$impl_m])* impl<$($t)*> $crate::__macro_helpers::Deref for $for { type Target = $superclass; diff --git a/crates/objc2/src/macros/extern_methods.rs b/crates/objc2/src/macros/extern_methods.rs index 3eb155460..035e1fddf 100644 --- a/crates/objc2/src/macros/extern_methods.rs +++ b/crates/objc2/src/macros/extern_methods.rs @@ -1,7 +1,7 @@ /// Define methods on an external class. /// -/// This is a convenience macro to easily generate associated functions and -/// methods that call [`msg_send!`] or [`msg_send_id!`] appropriately. +/// This is a convenience macro to generate associated functions and methods +/// that call [`msg_send!`] or [`msg_send_id!`] appropriately. /// /// [`msg_send!`]: crate::msg_send /// [`msg_send_id!`]: crate::msg_send_id @@ -31,11 +31,12 @@ /// work correctly, due to implementation difficulty - if you have a concrete /// use-case, please [open an issue], then we can discuss it. /// -/// The name of the function doesn't matter for out purposes, but is of course -/// what the user will use to access the functionality. +/// The name of the function will be used for the resulting function that the +/// user will use to access the functionality, but is otherwise not used by +/// the macro. /// -/// If you specify a function/method with a body, the macro will simply ignore -/// it. +/// If you specify a function/method with a body, the macro will output it +/// unchanged. /// /// ["associated functions"]: https://doc.rust-lang.org/reference/items/associated-items.html#methods /// ["methods"]: https://doc.rust-lang.org/reference/items/associated-items.html#methods diff --git a/crates/objc2/src/macros/extern_protocol.rs b/crates/objc2/src/macros/extern_protocol.rs index da4a71fb0..b7b5bf984 100644 --- a/crates/objc2/src/macros/extern_protocol.rs +++ b/crates/objc2/src/macros/extern_protocol.rs @@ -8,8 +8,8 @@ /// /// This macro will create an `unsafe` trait with methods which all have /// default implementations, such that an object that conforms to the protocol -/// can simply write `unsafe impl MyProtocol for MyClass {}`, and get access -/// to the functionality exposed by the protocol. +/// can write `unsafe impl MyProtocol for MyClass {}`, and get access to the +/// functionality exposed by the protocol. /// /// Objective-C has a smart feature where you can write `id`, and /// then work with the protocol as-if it was an object; this is very similar @@ -43,8 +43,7 @@ /// future when implementing protocols in [`declare_class!`]. /// /// This macro otherwise shares similarities with [`extern_class!`] and -/// [`extern_methods!`], if you are familiar with those, it should be fairly -/// straightforward to use. +/// [`extern_methods!`]. /// /// [`ProtocolObject`]: crate::runtime::ProtocolObject /// [`ProtocolType`]: crate::ProtocolType diff --git a/crates/objc2/src/macros/mod.rs b/crates/objc2/src/macros/mod.rs index f2efe7164..626666851 100644 --- a/crates/objc2/src/macros/mod.rs +++ b/crates/objc2/src/macros/mod.rs @@ -753,17 +753,17 @@ macro_rules! __class_inner { /// /// # `bool` handling /// -/// Objective-C's `BOOL` is different from Rust's [`bool`], and hence a -/// conversion step must be performed before using it. This is _very_ easy to -/// forget (because it'll happen to work in _most_ cases), so for ease of use, -/// this macro does the conversion step automatically whenever the argument or -/// return type is `bool`! +/// Objective-C's `BOOL` is slightly different from Rust's [`bool`], and hence +/// a conversion step must be performed before using it. This is _very_ easy +/// to forget (because it'll happen to work in _most_ cases), so this macro +/// does the conversion step automatically whenever an argument or the return +/// type is `bool`. /// -/// That means that any Objective-C method that take or return `BOOL` can -/// simply be translated to use `bool` on the Rust side. +/// That means that any Objective-C method that take or return `BOOL` can be +/// translated to use `bool` on the Rust side. /// /// If you want to handle the conversion explicitly, or the Objective-C method -/// expects a pointer to a `BOOL`, use [`runtime::Bool`] instead. +/// expects e.g. a pointer to a `BOOL`, use [`runtime::Bool`] instead. /// /// [`runtime::Bool`]: crate::runtime::Bool /// @@ -771,8 +771,8 @@ macro_rules! __class_inner { /// # Out-parameters /// /// Parameters like `NSString**` in Objective-C are passed by "writeback", -/// which essentially just means that the callee autoreleases any value that -/// they may write into the parameter. +/// which means that the callee autoreleases any value that they may write +/// into the parameter. /// /// This macro has support for passing such parameters using the following /// types: @@ -845,7 +845,8 @@ macro_rules! __class_inner { /// /// 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 -/// (of course except if the variable is inside [`std::cell::UnsafeCell`]). +/// (except if the variable is inside [`std::cell::UnsafeCell`] or +/// derivatives). /// /// 5. If the receiver is a raw pointer it must be valid (aligned, /// dereferenceable, initialized and so on). Messages to `null` pointers @@ -1061,9 +1062,10 @@ macro_rules! msg_send_bool { /// /// # A little history /// -/// Objective-C's type system is... limited, so you can't easily tell who is -/// responsible for releasing an object. To remedy this problem, Apple/Cocoa -/// introduced approximately the following rule: +/// Objective-C's type system is... limited, so you can't tell without +/// consulting the documentation who is responsible for releasing an object. +/// To remedy this problem, Apple/Cocoa introduced (approximately) the +/// following rule: /// /// The caller is responsible for releasing objects return from methods that /// begin with `new`, `alloc`, `copy`, `mutableCopy` or `init`, and method diff --git a/crates/objc2/src/message/gnustep.rs b/crates/objc2/src/message/gnustep.rs index bbf65e4d9..59611021b 100644 --- a/crates/objc2/src/message/gnustep.rs +++ b/crates/objc2/src/message/gnustep.rs @@ -29,7 +29,7 @@ where // If `receiver` is NULL, objc_msg_lookup will return a standard C-method // taking two arguments, the receiver and the selector. Transmuting and // calling such a function with multiple parameters is UB, so instead we - // just return NULL directly. + // return NULL directly. if receiver.is_null() { // SAFETY: Caller guarantees that messages to NULL-receivers only // return pointers, and a mem::zeroed pointer is just a NULL-pointer. diff --git a/crates/objc2/src/mutability.rs b/crates/objc2/src/mutability.rs index 686fc0b59..631b6df69 100644 --- a/crates/objc2/src/mutability.rs +++ b/crates/objc2/src/mutability.rs @@ -89,7 +89,7 @@ pub struct Immutable { /// Rust assume are unique. /// - As a special case of that, `-[NSCopying copy]` and /// `-[NSMutableCopying mutableCopy]`, if implemented, must return a new -/// instance (e.g. they cannot just `retain` the instance). +/// instance (e.g. cannot be implemented by just `retain`-ing the instance). #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)] pub struct Mutable { inner: Never, diff --git a/crates/objc2/src/rc/allocated.rs b/crates/objc2/src/rc/allocated.rs index 4ad13276b..8ef5e0229 100644 --- a/crates/objc2/src/rc/allocated.rs +++ b/crates/objc2/src/rc/allocated.rs @@ -9,7 +9,7 @@ use crate::Message; /// A marker type that can be used to indicate that the object has been /// allocated but not initialized. /// -/// The reason we use `Allocated` / `Option>` instead of just +/// The reason we use `Allocated` / `Option>` instead of /// `*mut T` is: /// - To allow releasing allocated objects, e.g. in the face of panics. /// - To safely know the object is valid (albeit uninitialized). @@ -21,8 +21,8 @@ use crate::Message; // object as an optimization, and then only figure out afterwards whether it // needs to allocate, or if it can store an `NSString` internally. // Similarly, while e.g. `+[NSData alloc]` may return a unique object, -// calling `-[NSData init]` afterwards could easily just return a shared -// empty `NSData` instance. +// calling `-[NSData init]` afterwards could return a shared empty `NSData` +// instance. #[repr(transparent)] #[derive(Debug)] pub struct Allocated { @@ -63,7 +63,7 @@ impl Allocated { let ptr = this.map(|this| ManuallyDrop::new(this).ptr); // Difficult to write this in an ergonomic way with `?Sized`, so we - // just hack it with transmute. + // hack it with transmute. // // SAFETY: `Option>` has the same size as `*mut T`. unsafe { mem::transmute::>, *mut T>(ptr) } diff --git a/crates/objc2/src/rc/autorelease.rs b/crates/objc2/src/rc/autorelease.rs index 016f0da41..d38b9c325 100644 --- a/crates/objc2/src/rc/autorelease.rs +++ b/crates/objc2/src/rc/autorelease.rs @@ -258,8 +258,8 @@ auto_trait! { /// With the `"unstable-autoreleasesafe"` feature enabled, this is an auto /// trait that is implemented for all types except [`AutoreleasePool`]. /// - /// Otherwise it is just a dummy trait that is implemented for all types; - /// the safety invariants are checked with debug assertions instead. + /// Otherwise it is a dummy trait that is implemented for all types; the + /// safety invariants are checked with debug assertions instead. /// /// You should not normally need to implement this trait yourself. /// @@ -270,9 +270,8 @@ auto_trait! { /// pool. So if you reimplement the [`AutoreleasePool`] struct or /// likewise, this should be negatively implemented for that. /// - /// This can easily be accomplished with an - /// `PhantomData>` if the `"unstable-autoreleasesafe"` - /// feature is enabled. + /// This can be accomplished with an `PhantomData>` if + /// the `"unstable-autoreleasesafe"` feature is enabled. /// /// /// # Examples @@ -433,8 +432,8 @@ where // - The pools are guaranteed to be dropped in the reverse order they were // created (since you can't possibly "interleave" closures). // - // This would not work if we e.g. just allowed users to create pools on - // the stack, since they could then safely control the drop order. + // This would not work if we e.g. allowed users to create pools on the + // stack, since they could then safely control the drop order. let pool = unsafe { Pool::new() }; let res = f(AutoreleasePool::new(Some(&pool))); unsafe { pool.drain() }; @@ -447,8 +446,8 @@ where /// without the overhead of actually creating and draining the pool. /// /// Any function boundary in Objective-C is an implicit autorelease pool, so -/// you'd just do `id obj2 = [obj autorelease]` and be done with it - but we -/// do this using a closure instead because we need some way to bound the +/// there you'd do `id obj2 = [obj autorelease]` and be done with it - but we +/// do this using a closure instead because we need some way to bind the /// lifetime of any objects released to the pool. /// /// @@ -468,7 +467,8 @@ where /// // do anything. /// println!("{obj:?}"); /// }); -/// // But it is of course still not usable here +/// +/// // But it is not usable here, since the outer pool has been closed /// ``` /// /// Like [`autoreleasepool`], you can't extend the lifetime of an object to @@ -504,7 +504,7 @@ pub fn autoreleasepool_leaking(f: F) -> T where for<'pool> F: FnOnce(AutoreleasePool<'pool>) -> T, { - // SAFETY: This is effectively what most Objective-C code does; they just + // SAFETY: This is effectively what most Objective-C code does; they // assume that there's an autorelease pool _somewhere_ in the call stack // above it, and then use their autoreleased objects for a duration that // is guaranteed to be shorter than that. diff --git a/crates/objc2/src/rc/id.rs b/crates/objc2/src/rc/id.rs index 63bea1b31..d4c533554 100644 --- a/crates/objc2/src/rc/id.rs +++ b/crates/objc2/src/rc/id.rs @@ -46,14 +46,14 @@ use crate::{ffi, ClassType, Message}; /// /// # Forwarding implementations /// -/// Since `Id` is a smart pointer, it naturally [`Deref`]s to `T`, and -/// similarly implements [`DerefMut`] when mutable. +/// Since `Id` is a smart pointer, it [`Deref`]s to `T`, and similarly +/// implements [`DerefMut`] when mutable. /// -/// On top of this, it also forwards the implementation of a bunch of standard -/// library traits such as [`PartialEq`], [`AsRef`], and so on, so that it -/// becomes easy to use e.g. `Id` as if it was just an `NSString`. -/// (Having just `NSString` is not possible since Objective-C objects cannot -/// live on the stack, but instead must reside on the heap). +/// It also forwards the implementation of a bunch of standard library traits +/// such as [`PartialEq`], [`AsRef`], and so on, so that it becomes possible +/// to use e.g. `Id` as if it was `NSString`. (Having `NSString` +/// directly is not possible since Objective-C objects cannot live on the +/// stack, but instead must reside on the heap). /// /// Note that because of current limitations in the Rust trait system, some /// traits like [`Default`], [`IntoIterator`], [`FromIterator`], [`From`] and @@ -103,7 +103,7 @@ use crate::{ffi, ClassType, Message}; /// // SAFETY: The types are correct, and it is safe to call the `new` /// // selector on `NSString`. /// let string: Id = unsafe { msg_send_id![NSString::class(), new] }; -/// // Or simply: +/// // Or: /// // let string = NSString::new(); /// /// // Methods on `NSString` is usable via. `Deref` @@ -422,8 +422,8 @@ impl Id { // Ideally, we'd be able to specify that the above call should never // be tail-call optimized (become a `jmp` instruction instead of a // `call`); Rust doesn't really have a way of doing this currently, so - // we just emit a simple `nop` to make such tail-call optimizations - // less likely to occur. + // we emit a `nop` to make such tail-call optimizations less likely to + // occur. // // This is brittle! We should find a better solution! #[cfg(all(feature = "apple", not(target_os = "windows"), target_arch = "x86_64"))] @@ -473,7 +473,7 @@ impl Id { /// This is an associated method, and must be called as /// `Id::autorelease(obj, pool)`. #[doc(alias = "objc_autorelease")] - #[must_use = "If you don't intend to use the object any more, just drop it as usual"] + #[must_use = "if you don't intend to use the object any more, drop it as usual"] #[inline] #[allow(clippy::needless_lifetimes)] pub fn autorelease<'p>(this: Self, pool: AutoreleasePool<'p>) -> &'p T { @@ -493,7 +493,7 @@ impl Id { /// This is an associated method, and must be called as /// `Id::autorelease_mut(obj, pool)`. #[doc(alias = "objc_autorelease")] - #[must_use = "If you don't intend to use the object any more, just drop it as usual"] + #[must_use = "if you don't intend to use the object any more, drop it as usual"] #[inline] #[allow(clippy::needless_lifetimes)] pub fn autorelease_mut<'p>(this: Self, pool: AutoreleasePool<'p>) -> &'p mut T @@ -579,7 +579,7 @@ impl Id { /// /// [`declare_class!`]: crate::declare_class #[doc(alias = "objc_autoreleaseReturnValue")] - #[must_use = "If you don't intend to use the object any more, just drop it as usual"] + #[must_use = "if you don't intend to use the object any more, drop it as usual"] #[inline] pub fn autorelease_return(this: Self) -> *mut T { Self::autorelease_return_option(Some(this)) @@ -596,8 +596,8 @@ where // SAFETY: // - The casted-to type is a superclass of the type. // - Both types are `'static`, so no lifetime information is lost - // (this could maybe be relaxed a bit, but let's just be on the safe - // side for now). + // (this could maybe be relaxed a bit, but let's be on the safe side + // for now). unsafe { Self::cast::(this) } } } diff --git a/crates/objc2/src/rc/id_traits.rs b/crates/objc2/src/rc/id_traits.rs index 31cbfa01d..38db37acc 100644 --- a/crates/objc2/src/rc/id_traits.rs +++ b/crates/objc2/src/rc/id_traits.rs @@ -8,8 +8,8 @@ use crate::mutability::{IsAllocableAnyThread, IsMutable}; pub trait DefaultId: IsAllocableAnyThread { /// The default [`Id`] for a type. /// - /// On most objects the implementation would just be sending a message to - /// the `new` selector. + /// On most objects the implementation would be sending a message to the + /// `new` selector. fn default_id() -> Id; } @@ -23,7 +23,7 @@ impl Default for Id { /// Helper trait to implement [`IntoIterator`] on [`Id`]. /// /// This should be implemented in exactly the same fashion as if you were -/// just implementing `IntoIterator` for your type normally. +/// implementing `IntoIterator` for your type normally. // // Note that [`Box` gets to cheat with regards moves][box-move], so // `boxed.into_iter()` is possible, while `id.into_iter()` is not possible @@ -40,7 +40,7 @@ pub trait IdIntoIterator { /// Creates an iterator from an [`Id`]. /// /// You would normally not call this function directly; instead, you'd - /// just call [`into_iter`](IntoIterator::into_iter) on an [`Id`]. + /// call [`into_iter`](IntoIterator::into_iter) on an [`Id`]. fn id_into_iter(this: Id) -> Self::IntoIter; } @@ -111,7 +111,7 @@ where /// Helper trait to implement [`FromIterator`] on [`Id`]. /// /// This should be implemented in exactly the same fashion as if you were -/// just implementing `FromIterator` for your type normally. +/// implementing `FromIterator` for your type normally. pub trait IdFromIterator: Sized { /// Creates an `Id` from an iterator. fn id_from_iter(iter: I) -> Id diff --git a/crates/objc2/src/rc/writeback.rs b/crates/objc2/src/rc/writeback.rs index 887f45090..a972fe3b6 100644 --- a/crates/objc2/src/rc/writeback.rs +++ b/crates/objc2/src/rc/writeback.rs @@ -4,8 +4,8 @@ //! //! //! Note: We differ from that in that we do not create a temporary, whoose -//! address we then work on; instead, we just directly reuse the pointer that -//! the user provides (since, if it's a mutable pointer, we know that it's not +//! address we then work on; instead, we directly reuse the pointer that the +//! user provides (since, if it's a mutable pointer, we know that it's not //! shared elsewhere in the program, and hence it is safe to modify directly). use core::mem::ManuallyDrop; use core::ptr::NonNull; @@ -15,7 +15,7 @@ use crate::rc::Id; use crate::Message; // Note the `'static` bound here - this may not be necessary, but I'm unsure -// of the exact requirements, so we better just keep it for now. +// of the exact requirements, so we better keep it for now. impl EncodeConvertArgument for &mut Id { // We use `*mut T` as the inner value instead of `NonNull`, since we // want to do debug checking that the value hasn't unexpectedly been @@ -25,8 +25,8 @@ impl EncodeConvertArgument for &mut Id { type __StoredBeforeMessage = ( // A copy of the argument, so that we can retain it after the message - // send. Ideally, we'd just work with e.g. `&mut *mut T`, but we can't - // do that inside the generic context of `MessageArguments::__invoke`. + // send. Ideally, we'd work with e.g. `&mut *mut T`, but we can't do + // that inside the generic context of `MessageArguments::__invoke`. Self::__Inner, // A pointer to the old value stored in the `Id`, so that we can // release if after the message send. @@ -55,7 +55,7 @@ impl EncodeConvertArgument for &mut Id { #[inline] unsafe fn __process_after_message_send((ptr, old): Self::__StoredBeforeMessage) { - // In terms of provenance, we roughly just want to do the following: + // In terms of provenance, we roughly want to do the following: // ``` // fn do(value: &mut Id) { // let old = value.clone(); @@ -91,8 +91,8 @@ impl EncodeConvertArgument for &mut Id { // safe to retain at this point. let new: Option> = unsafe { Id::retain(*ptr.as_ptr()) }; // We ignore the result of `retain`, since it always returns the same - // value as was given (and it would just be unnecessary work to write - // that value back into `ptr` again). + // value as was given (and it would be unnecessary work to write that + // value back into `ptr` again). let _new = ManuallyDrop::new(new); #[cfg(debug_assertions)] if _new.is_none() { diff --git a/crates/objc2/src/runtime/mod.rs b/crates/objc2/src/runtime/mod.rs index 20d820962..5dfcfcf18 100644 --- a/crates/objc2/src/runtime/mod.rs +++ b/crates/objc2/src/runtime/mod.rs @@ -75,15 +75,16 @@ pub const NO: ffi::BOOL = ffi::NO; /// A method selector. /// -/// The Rust equivalent of Objective-C's `SEL` type. You can easily create -/// this using the [`sel!`] macro. +/// The Rust equivalent of Objective-C's `SEL` type. You can create this +/// statically using the [`sel!`] macro. /// -/// The main reason the Objective-C runtime uses a custom types for selectors -/// is to support efficient comparison - a selector is effectively just an -/// [interned string], so this makes that very easy! +/// The main reason the Objective-C runtime uses a custom type for selectors, +/// as opposed to a plain c-string, is to support efficient comparison - a +/// a selector is effectively an [interned string], so this makes equiality +/// comparisons very cheap. /// -/// This guarantees the null-pointer optimization, namely that `Option` -/// is the same size as `Sel`. +/// This struct guarantees the null-pointer optimization, namely that +/// `Option` is the same size as `Sel`. /// /// [`sel!`]: crate::sel /// [interned string]: https://en.wikipedia.org/wiki/String_interning @@ -218,7 +219,7 @@ impl Sel { let ptr = unsafe { ffi::sel_getName(self.as_ptr()) }; // SAFETY: The string is a valid C-style NUL-terminated string, and // likely has static lifetime since the selector has static lifetime - // (though we bind it to `&self` just to be safe). + // (though we bind it to `&self` to be safe). let name = unsafe { CStr::from_ptr(ptr) }; str::from_utf8(name.to_bytes()).unwrap() } @@ -232,7 +233,7 @@ impl Sel { } } -// `ffi::sel_isEqual` is just pointer comparison on Apple (the documentation +// `ffi::sel_isEqual` uses pointer comparison on Apple (the documentation // explicitly notes this); so as an optimization, let's do that as well! #[cfg(feature = "apple")] standard_pointer_impls!(Sel); @@ -259,7 +260,7 @@ impl hash::Hash for Sel { } } -// SAFETY: `Sel` is FFI compatible, and the encoding is of course `Sel`. +// SAFETY: `Sel` is FFI compatible, and the encoding is `Sel`. unsafe impl Encode for Sel { const ENCODING: Encoding = Encoding::Sel; } @@ -267,8 +268,8 @@ unsafe impl Encode for Sel { unsafe impl OptionEncode for Sel {} // RefEncode is not implemented for Sel, because there is literally no API -// that takes &Sel, but the user could easily get confused and accidentally -// attempt that. +// that takes &Sel, while the user could get confused and accidentally attempt +// that. // SAFETY: Sel is immutable (and can be retrieved from any thread using the // `sel!` macro). @@ -993,8 +994,8 @@ impl Object { /// Sets the value of the ivar with the given name. /// - /// This is just a helpful shorthand for [`Object::ivar_mut`], see that - /// for more information. + /// This is a shorthand for [`Object::ivar_mut`], see that for more + /// information. /// /// /// # Safety diff --git a/crates/objc2/src/runtime/nszone.rs b/crates/objc2/src/runtime/nszone.rs index ed1889602..1f2235bd2 100644 --- a/crates/objc2/src/runtime/nszone.rs +++ b/crates/objc2/src/runtime/nszone.rs @@ -54,8 +54,8 @@ unsafe impl RefEncode for NSZone { // Name of zone Encoding::Object, // Next zone - note that the contents of this doesn't matter, - // since this is nested far enough that the encoding string just - // ends up ignoring it. + // since this is nested far enough that the encoding string ends + // up ignoring it. Encoding::Pointer(&Encoding::Struct("_NSZone", &[])), ], )); diff --git a/crates/objc2/src/runtime/protocol_object.rs b/crates/objc2/src/runtime/protocol_object.rs index eb9aa50c1..e99497d46 100644 --- a/crates/objc2/src/runtime/protocol_object.rs +++ b/crates/objc2/src/runtime/protocol_object.rs @@ -113,7 +113,7 @@ impl ProtocolObject

{ // SAFETY: // - The type can be represented as the casted-to type. // - Both types are `'static` (this could maybe be relaxed a bit, but - // let's just be on the safe side)! + // let's be on the safe side)! unsafe { Id::cast::(obj) } } } diff --git a/crates/test-assembly/crates/test_fast_enumeration/lib.rs b/crates/test-assembly/crates/test_fast_enumeration/lib.rs index 05c2ff960..d66c41388 100644 --- a/crates/test-assembly/crates/test_fast_enumeration/lib.rs +++ b/crates/test-assembly/crates/test_fast_enumeration/lib.rs @@ -5,7 +5,7 @@ use core::hint::black_box; use icrate::Foundation::array::Iter; use icrate::Foundation::{NSArray, NSObject}; -// Should ideally just be zero-initialized. +// Should ideally be a fast zero-initialization. #[no_mangle] fn iter_create(array: &NSArray) -> Iter<'_, NSObject> { array.iter() diff --git a/crates/tests/src/test_encode_utils.rs b/crates/tests/src/test_encode_utils.rs index 96ed71b5f..5f7b15b84 100644 --- a/crates/tests/src/test_encode_utils.rs +++ b/crates/tests/src/test_encode_utils.rs @@ -23,8 +23,7 @@ unsafe fn assert_encoding(s: *const c_char, e: Encoding) { #[allow(unused)] unsafe fn assert_str(s: *const c_char, expected: T) { let s = CStr::from_ptr(s).to_str().unwrap(); - // Exact comparison to ensure we catch regressions (and that they are not - // just masked by ). + // Exact comparison to ensure we catch regressions. assert_eq!(s, expected.to_string()); } @@ -277,8 +276,8 @@ assert_types! { UINT32 => u32, UINT64 => u64, - // `intptr`, `uintptr` and `size_t` are cfg-guarded because they are - // simply just too much of a hassle to get working on this old platform. + // `intptr`, `uintptr` and `size_t` are cfg-guarded because they are too + // much of a hassle to get working on old platforms. // // Pointers (`intptr*`) works, but not plain `intptr`...