Add a few more links to external documentation

Author: madsmtm

.github/workflows/ci.yml

@@ -584,6 +584,8 @@ jobs:
       ASMFLAGS: ${{ matrix.cflags }}
       LDFLAGS: ${{ matrix.cflags }}
       ARGS: --no-default-features --features=std,${{ matrix.runtime }}
+      # http://wiki.gnustep.org/index.php/Building_GNUstep_under_Debian_FreeBSD#installing_gnustep-make
+      RUNTIME_VERSION: gnustep-${{ matrix.libobjc2 }}
 
     steps:
     - uses: actions/checkout@v3

crates/header-translator/src/rust_type.rs

@@ -122,6 +122,10 @@ impl AttributeParser<'_, '_> {
         }
     }
 
+    /// We completely ignore `__kindof` in Rust as it is done in Swift, since
+    /// it only exists to allow legacy Objective-C code to continue compiling.
+    ///
+    /// See <https://lapcatsoftware.com/articles/kindof.html>
     fn is_kindof(&mut self, position: ParsePosition) -> bool {
         self.strip("__kindof", position)
     }

crates/objc-sys/build.rs

@@ -171,6 +171,7 @@ fn main() {
                 // The fragile runtime is expected on i686-apple-darwin, see:
                 // https://github.com/llvm/llvm-project/blob/release/13.x/clang/lib/Driver/ToolChains/Darwin.h#L228-L231
                 // https://github.com/llvm/llvm-project/blob/release/13.x/clang/lib/Driver/ToolChains/Clang.cpp#L3639-L3640
+                // https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Articles/ocrtVersionsPlatforms.html
                 (MacOS(version), "x86") => format!("macosx-fragile-{version}"),
                 (MacOS(version), _) => format!("macosx-{version}"),
                 (IOS(version), _) => format!("ios-{version}"),

crates/objc-sys/src/lib.rs

@@ -2,13 +2,15 @@
 //!
 //! These bindings contain almost no documentation, so it is highly
 //! recommended to read the documentation of the original libraries:
-//! - Apple's [official documentation][apple].
+//! - Apple's [documentation about the Objective-C runtime][runtime-guide].
+//! - Apple's [runtime reference][apple].
 //! - Apple's `objc4` [source code][objc4], in particular `runtime.h`.
 //! - GNUStep's `libobjc2` [source code][libobjc2], in particular `runtime.h`.
 //!
 //! See also the [`README.md`](https://crates.io/crates/objc-sys) for more
 //! background information, and for how to configure the desired runtime.
 //!
+//! [runtime-guide]: https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Introduction/Introduction.html
 //! [apple]: https://developer.apple.com/documentation/objectivec/objective-c_runtime?language=objc
 //! [libobjc2]: https://github.com/gnustep/libobjc2/tree/v2.1/objc
 //! [objc4]: https://github.com/apple-oss-distributions/objc4

crates/objc-sys/src/various.rs

@@ -45,6 +45,7 @@ extern_c_unwind! {
 extern_c! {
     #[cfg(any(doc, not(objfw)))]
     pub fn imp_getBlock(imp: IMP) -> *mut objc_object;
+    // See also <https://landonf.org/code/objc/imp_implementationWithBlock.20110413.html>
     #[cfg(any(doc, not(objfw)))]
     pub fn imp_implementationWithBlock(block: *mut objc_object) -> IMP;
     #[cfg(any(doc, not(objfw)))]

crates/objc2/src/runtime/message_receiver.rs

@@ -35,6 +35,10 @@ macro_rules! conditional_try {
     }};
 }
 
+// More information on how objc_msgSend works:
+// <https://web.archive.org/web/20200118080513/http://www.friday.com/bbum/2009/12/18/objc_msgsend-part-1-the-road-map/>
+// <https://www.mikeash.com/pyblog/objc_msgsends-new-prototype.html>
+// <https://www.mikeash.com/pyblog/friday-qa-2012-11-16-lets-build-objc_msgsend.html>
 #[cfg(feature = "apple")]
 mod msg_send_primitive {
     #[allow(unused_imports)]
@@ -340,13 +344,13 @@ pub unsafe trait MessageReceiver: private::Sealed + Sized {
     /// Sends a message to the receiver with the given selector and arguments.
     ///
     /// The correct version of `objc_msgSend` will be chosen based on the
-    /// return type. For more information, see the section on "Sending
-    /// Messages" in Apple's [documentation][runtime].
+    /// return type. For more information, see [the Messaging section in
+    /// Apple's Objective-C Runtime Programming Guide][guide-messaging].
     ///
     /// If the selector is known at compile-time, it is recommended to use the
     /// [`msg_send!`] macro rather than this method.
     ///
-    /// [runtime]: https://developer.apple.com/documentation/objectivec/objective-c_runtime?language=objc
+    /// [guide-messaging]: https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Articles/ocrtHowMessagingWorks.html
     ///
     ///
     /// # Safety