Merge pull request #452 from madsmtm/doc

Improve examples and remove words that downplay the difficulty of a given task

Author: madsmtm

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)

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");

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,
 }

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.

crates/block2/src/block.rs

@@ -90,9 +90,9 @@ block_args_impl!(
 #[repr(C)]
 pub struct Block<A, R> {
     _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<ffi::Block_layout>,
     // To get correct variance on args and return types
     _p: PhantomData<fn(A) -> R>,

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

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.

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

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;

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