Update objc_encode documentation to mention new RefEncode type

Also moves the primary documentation into the README.md

Author: madsmtm

objc_encode/Cargo.toml

@@ -1,10 +1,11 @@
 [package]
 name = "objc-encode"
-version = "1.1.0" # Remember to update html_root_url in lib.rs
+# Remember to update html_root_url in lib.rs and README.md
+version = "1.1.0"
 authors = ["Steven Sheldon", "Mads Marquart <[email protected]>"]
 edition = "2018"
 
-description = "Objective-C type encoding creation and parsing."
+description = "Objective-C type-encodings"
 keywords = ["objective-c", "macos", "ios", "encode"]
 categories = [
     "development-tools::ffi",

objc_encode/README.md

@@ -1,64 +1,83 @@
-# `objc-encode`
+# `objc-encode` - Objective-C type-encoding in Rust
 
 [![Latest version](https://badgen.net/crates/v/objc-encode)](https://crates.io/crates/objc-encode)
 [![License](https://badgen.net/badge/license/MIT/blue)](../LICENSE.txt)
 [![Documentation](https://docs.rs/objc-encode/badge.svg)](https://docs.rs/objc-encode/)
 [![CI Status](https://github.com/madsmtm/objc/workflows/CI/badge.svg)](https://github.com/madsmtm/objc/actions)
 
-Objective-C type encoding creation and parsing in Rust.
+The Objective-C directive `@encode` encodes types as strings for usage in
+various places in the runtime.
 
-The Objective-C compiler encodes types as strings for usage in the runtime.
-This crate aims to provide a strongly-typed (rather than stringly-typed) way
-to create and describe these type encodings without memory allocation in Rust.
+This crate provides the `Encoding` type to describe and compare these
+type-encodings without memory allocation.
 
+Additionally it provides traits for annotating types that has a corresponding
+Objective-C encoding, respectively `Encode` for structs and `RefEncode` for
+references (and `EncodeArguments` for function arguments).
 
-## Implementing Encode
+These types are exported under the `objc` crate as well, so usually you would
+just use that crate.
 
-This crate declares an `Encode` trait that can be implemented for types that
-the Objective-C compiler can encode. Implementing this trait looks like:
+# Examples
 
-```rust
-use objc::{Encode, Encoding};
-
-#[cfg(target_pointer_width = "32")]
-type CGFloat = f32;
+Implementing `Encode` and `RefEncode`:
 
-#[cfg(target_pointer_width = "64")]
-type CGFloat = f64;
+```rust
+use objc_encode::{Encode, Encoding, RefEncode};
 
 #[repr(C)]
-struct CGPoint {
-    x: CGFloat,
-    y: CGFloat,
+struct MyObject {
+    a: f32,
+    b: bool,
 }
 
-unsafe impl Encode for CGPoint {
-    const ENCODING: Encoding<'static> =
-        Encoding::Struct("CGPoint", &[CGFloat::ENCODING, CGFloat::ENCODING]);
+unsafe impl Encode for MyObject {
+    const ENCODING: Encoding<'static> = Encoding::Struct(
+        "MyObject",
+        &[f32::ENCODING, bool::ENCODING
+    ]);
 }
-```
 
-For an example of how this works with more complex types, like structs
-containing structs, see the `core_graphics` example.
+assert_eq!(&MyObject::ENCODING, "{MyObject=fB}");
 
-## Comparing with encoding strings
+unsafe impl RefEncode for MyObject {
+    const ENCODING_REF: Encoding<'static> = Encoding::Pointer(&Self::ENCODING);
+}
+
+assert_eq!(&MyObject::ENCODING_REF, "^{MyObject=fB}");
+```
 
 An `Encoding` can be compared with an encoding string from the Objective-C
 runtime:
 
 ```rust
 use objc::Encode;
-
 assert!(&i32::ENCODING == "i");
 ```
 
-## Generating encoding strings
-
-Every `Encoding` implements `Display` as its string representation.
-This can be generated conveniently through the `to_string` method:
+`Encoding` implements `Display` as its string representation. This can be
+generated conveniently through the `to_string` method:
 
 ```rust
 use objc::Encode;
-
 assert_eq!(i32::ENCODING.to_string(), "i");
 ```
+
+See the [`examples`] folder for more complex usage.
+
+# Installation
+
+```toml
+[dependencies]
+objc-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/objc/tree/master/objc_encode/examples
+[`../LICENSE.txt`]: https://github.com/madsmtm/objc/blob/master/LICENSE.txt

objc_encode/src/lib.rs

@@ -1,46 +1,4 @@
-/*!
-Objective-C type encoding creation and parsing in Rust.
-
-The Objective-C compiler encodes types as strings for usage in the runtime.
-This crate aims to provide a strongly-typed (rather than stringly-typed) way
-to create and describe these type encodings without memory allocation in Rust.
-
-# Implementing Encode
-
-This crate declares an [`Encode`] trait that can be implemented for types that
-the Objective-C compiler can encode. Implementing this trait looks like:
-
-```ignore
-unsafe impl Encode for CGPoint {
-    const ENCODING: Encoding<'static> =
-        Encoding::Struct("CGPoint", &[CGFloat::ENCODING, CGFLOAT::ENCODING]);
-}
-```
-
-For an example of how this works with more complex types, like structs
-containing structs, see the `core_graphics` example.
-
-# Comparing with encoding strings
-
-An [`Encoding`] can be compared with an encoding string from the Objective-C
-runtime:
-
-```
-# use objc::Encode;
-assert!(&i32::ENCODING == "i");
-```
-
-# Generating encoding strings
-
-Every [`Encoding`] implements [`Display`][`core::fmt::Display`] as its string
-representation. This can be generated conveniently through the
-[`to_string`][`alloc::string::ToString::to_string`] method:
-
-```
-# use objc::Encode;
-assert_eq!(i32::ENCODING.to_string(), "i");
-```
-*/
+//! # Objective-C type-encoding
 
 #![no_std]
 #![warn(missing_docs)]