Merge pull request #54 from madsmtm/improve-readme

Improve READMEs

Author: madsmtm

README.md

@@ -1,5 +1,39 @@
-# [![Rust + \[Obj-C\]](assets/logo-small.png)](https://github.com/madsmtm/objc2) Objective-C in Rust
+# [![Rust + \[Obj-C\]](assets/logo-small.png)](https://github.com/madsmtm/objc2) <br> Objective-C in Rust
 
 [![License](https://badgen.net/badge/license/MIT/blue)](../LICENSE.txt)
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
+
+# DISCLAIMER! These crates are work in progress, and should not be used in production environments. Use the battle-tested `objc` family instead!
+
+
+## License
+
+This project is licensed under the MIT license, see [`LICENSE.txt`].
+
+Work is in progress to make it dual-licensed under the Apache License
+(Version 2.0) as well, see [this][#23].
+
+[`LICENSE.txt`]: https://github.com/madsmtm/objc2/blob/master/LICENSE.txt
+[#23]: https://github.com/madsmtm/objc2/issues/23
+
+
+## Acknowledgements
+
+This repository is originally a fork of [`objc`], with the following
+projects merged into it (see reasoning for the fork [here][origin-issue-101]):
+- [`objc-encode`](https://github.com/SSheldon/rust-objc-encode)
+- [`objc_exception`](https://github.com/SSheldon/rust-objc-exception)
+- [`objc_id`](https://github.com/SSheldon/rust-objc-id)
+- [`objc-foundation`](https://github.com/SSheldon/rust-objc-foundation)
+- [`block`](https://github.com/SSheldon/rust-block)
+
+These were created almost solely by [@SSheldon](https://github.com/SSheldon),
+so a huge thanks for their fantastic work on these crates!
+
+This project also draws heavy inspiration from [`fruity`] and [`objrs`].
+
+[`objc`]: https://github.com/SSheldon/rust-objc
+[origin-issue-101]: https://github.com/SSheldon/rust-objc/issues/101
+[`fruity`]: https://github.com/nvzqz/fruity
+[`objrs`]: https://gitlab.com/objrs/objrs

objc2/README.md

@@ -6,7 +6,7 @@
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
 
-Objective-C Runtime bindings and wrapper for Rust.
+Objective-C runtime bindings and interface for Rust.
 
 ## Messaging objects
 

objc2_block/Cargo.toml

@@ -5,7 +5,7 @@ version = "0.1.6"
 authors = ["Steven Sheldon", "Mads Marquart <mads@marquart.dk>"]
 edition = "2018"
 
-description = "Interface for Apple's C language extension of blocks."
+description = "Apple's C language extension of blocks"
 keywords = ["objective-c", "macos", "ios", "blocks"]
 categories = [
     "api-bindings",

objc2_block/README.md

@@ -6,7 +6,7 @@
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
 
-Rust interface for Apple's C language extension of blocks.
+Apple's C language extension of blocks in Rust.
 
 For more information on the specifics of the block implementation, see
 Clang's documentation: http://clang.llvm.org/docs/Block-ABI-Apple.html

objc2_block_sys/README.md

@@ -6,7 +6,7 @@
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
 
-Raw Rust bindings to Apple's C language extension of blocks
+Raw Rust bindings to Apple's C language extension of blocks.
 
 ## Runtime Support
 

objc2_encode/README.md

@@ -1,11 +1,13 @@
-# `objc2_encode` - Objective-C type-encoding in Rust
+# `objc2_encode`
 
 [![Latest version](https://badgen.net/crates/v/objc2_encode)](https://crates.io/crates/objc2_encode)
 [![License](https://badgen.net/badge/license/MIT/blue)](../LICENSE.txt)
 [![Documentation](https://docs.rs/objc2_encode/badge.svg)](https://docs.rs/objc2_encode/)
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
 
+Objective-C type-encoding in Rust.
+
 The Objective-C directive `@encode` encodes types as strings for usage in
 various places in the runtime.
 
@@ -19,7 +21,8 @@ references (and `EncodeArguments` for function arguments).
 These types are exported under the `objc2` crate as well, so usually you would
 just use that.
 
-# Examples
+
+## Examples
 
 Implementing `Encode` and `RefEncode`:
 
@@ -66,19 +69,12 @@ assert_eq!(i32::ENCODING.to_string(), "i");
 
 See the [`examples`] folder for more complex usage.
 
-# Installation
+[`examples`]: https://github.com/madsmtm/objc2/tree/master/objc2_encode/examples
+
+
+## Installation
 
 ```toml
 [dependencies]
 objc2_encode = "1.1.0"
 ```
-
-# License
-
-This project is licensed under the MIT license, see [`../LICENSE.txt`].
-
-Work is in progress to make it dual-licensed under the Apache License
-(Version 2.0) as well.
-
-[`examples`]: https://github.com/madsmtm/objc2/tree/master/objc2_encode/examples
-[`../LICENSE.txt`]: https://github.com/madsmtm/objc2/blob/master/LICENSE.txt

objc2_exception/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.2" # Remember to update html_root_url in lib.rs
 authors = ["Steven Sheldon", "Mads Marquart <mads@marquart.dk>"]
 edition = "2018"
 
-description = "Objective-C's throw and try/catch statements."
+description = "Objective-C's @throw and @try/@catch statements"
 keywords = ["objective-c", "macos", "ios", "try", "catch"]
 categories = [
     "api-bindings",

objc2_exception/README.md

@@ -5,3 +5,5 @@
 [![Documentation](https://docs.rs/objc2_exception/badge.svg)](https://docs.rs/objc2_exception/)
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
+
+Objective-C's @throw and @try/@catch statements in Rust.

objc2_foundation/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.1" # Remember to update html_root_url in lib.rs
 authors = ["Steven Sheldon", "Mads Marquart <mads@marquart.dk>"]
 edition = "2018"
 
-description = "Bindings to the Objective-C Foundation framework."
+description = "Bindings to the Objective-C Foundation framework"
 keywords = ["objective-c", "macos", "ios", "cocoa", "uikit"]
 categories = [
     "api-bindings",

objc2_foundation/README.md

@@ -5,3 +5,5 @@
 [![Documentation](https://docs.rs/objc2_foundation/badge.svg)](https://docs.rs/objc2_foundation/)
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
+
+Bindings to the Objective-C `Foundation` framework in Rust.

objc2_foundation_derive/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.0.1" # Remember to update html_root_url in lib.rs
 authors = ["Steven Sheldon", "Mads Marquart <mads@marquart.dk>"]
 edition = "2018"
 
-description = "Procedural macros for deriving traits from objc2_foundation."
+description = "Procedural macros for deriving traits from objc2_foundation"
 keywords = ["objective-c", "macos", "ios", "cocoa", "uikit"]
 categories = [
     "api-bindings",

objc2_foundation_derive/README.md

@@ -5,3 +5,8 @@
 [![Documentation](https://docs.rs/objc2_foundation_derive/badge.svg)](https://docs.rs/objc2_foundation_derive/)
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
+
+WIP!
+
+This crate will be exposed under a `derive` flag in `objc2_foundation`, and so
+should not need to be used directly.

objc2_sys/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.0.0" # Remember to update html_root_url in lib.rs
 authors = ["Mads Marquart <mads@marquart.dk>"]
 edition = "2018"
 
-description = "Raw bindings to Objective-C runtimes"
+description = "Raw bindings to the Objective-C runtime and ABI"
 keywords = ["objective-c", "macos", "ios", "objc_msgSend", "sys"]
 categories = [
     "external-ffi-bindings",

objc2_sys/README.md

@@ -6,7 +6,7 @@
 [![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
 [![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
 
-Raw Rust bindings to core Objective-C runtimes and ABIs.
+Raw Rust bindings to the Objective-C runtime and ABI.
 
 ## Runtime Support