Docs and keywords

Cargo.toml

@@ -6,6 +6,7 @@ resolver = "2"
 version = "0.2.0-beta.0"
 authors = ["QuarticCat <[email protected]>"]
 description = "Ergonomic tagged pointer"
+keywords = ["enum", "pointer", "tag", "tagged", "tagging"]
 readme = "README.md"
 repository = "https://github.com/QuarticCat/enum-ptr"
 documentation = "https://docs.rs/enum-ptr/"

README.md

@@ -6,6 +6,7 @@
 *[0.2.0 beta](https://crates.io/crates/enum-ptr/0.2.0-beta.0) is released with a lot of new features. I need feedback from community.*
 
 This crate provides a custom derive macro `EnumPtr` to generate bridges between an enum `T` and `Compact<T>` with minimum cost. `Compact<T>` is the compact representation of `T`, and it is only one pointer wide.
+In other words, this crate is a library for defining tagged pointers in ergonomic way, even supporting different pointer types (`&`, `Box`, `Arc`, etc) as different `enum` variants.
 
 For example, the following code
 

enum-ptr-derive/Cargo.toml

@@ -4,6 +4,7 @@ name = "enum-ptr-derive"
 version.workspace = true
 authors.workspace = true
 description.workspace = true
+keywords.workspace = true
 readme.workspace = true
 repository.workspace = true
 documentation.workspace = true

enum-ptr/Cargo.toml

@@ -4,6 +4,7 @@ name = "enum-ptr"
 version.workspace = true
 authors.workspace = true
 description.workspace = true
+keywords.workspace = true
 readme.workspace = true
 repository.workspace = true
 documentation.workspace = true

enum-ptr/src/lib.rs

@@ -147,9 +147,11 @@
 //!
 //! ## Flavor 4: `map_ref` & `map_mut` *(legacy)*
 //!
-//! [`map_ref`](Compact::map_ref) and [`map_mut`](Compact::map_mut) will create
-//! temporary objects that drop as soon as your closure ends. They are
-//! important for internal implementations, but less useful for lib users.
+//! [`map_ref`](Compact::map_ref) and [`map_mut`](Compact::map_mut) will copy
+//! (= [`core::mem::transmute_copy`]) temporary objects out of its compact ones,
+//! that [`core::mem::forget`]-ed as soon as your closure ends, so that no
+//! destructor is needed to be run.  They are important for internal
+//! implementations, but less useful for lib users.
 //!
 //! <details>
 //! <summary>Click to show examples</summary>

enum-ptr/src/traits/aligned.rs

@@ -70,12 +70,32 @@ mod alloc_impl {
         const ALIGNMENT: usize = align_of::<T>();
     }
 
-    /// It makes assumption on the layout of `Rc`. Use it with caution.
+    /// Implementing [`Aligned`] for [`Rc`] relies on some undocumented
+    /// assumptions on its internal representation. However, it's very unlikely
+    /// for these assumptions to be violated in practice.
+    /// [`RcBox` is marked as `repr(C)` and reference counters are typed as `usize`][1].
+    /// Thus, its alignment is defined as [the highest of its members][2] (i.e. among
+    /// max of `usize` and `T`). Lastly, it's unconceivable for the type to be
+    /// lifted with `repr(C)` as commented or to start to use shorter
+    /// integers as counters.
+    ///
+    /// [1]: https://doc.rust-lang.org/1.81.0/src/alloc/rc.rs.html#286-291
+    /// [2]: https://doc.rust-lang.org/reference/type-layout.html#reprc-structs
     unsafe impl<T> Aligned for Rc<T> {
         const ALIGNMENT: usize = max(align_of::<T>(), align_of::<usize>());
     }
 
-    /// It makes assumption on the layout of `Arc`. Use it with caution.
+    /// Implementing [`Aligned`] for [`Arc`] relies on some undocumented
+    /// assumptions on its internal representation. However, it's very unlikely
+    /// for these assumptions to be violated in practice.
+    /// [`ArcInner` is marked as `repr(C)` and reference counters are typed as `usize`][1].
+    /// Thus, its alignment is defined as [the highest of its members][2] (i.e. among
+    /// max of `usize` and `T`). Lastly, it's unconceivable for the type to be
+    /// lifted with `repr(C)` as commented or to start to use shorter
+    /// integers as counters.
+    ///
+    /// [1]: https://doc.rust-lang.org/1.81.0/src/alloc/sync.rs.html#349-359
+    /// [2]: https://doc.rust-lang.org/reference/type-layout.html#reprc-structs
     unsafe impl<T> Aligned for Arc<T> {
         const ALIGNMENT: usize = max(align_of::<T>(), align_of::<usize>());
     }
@@ -84,12 +104,26 @@ mod alloc_impl {
         const ALIGNMENT: usize = align_of::<T>();
     }
 
-    /// It makes assumption on the layout of `Rc`. Use it with caution.
+    /// On top of the safety reasoning of `impl Align for Rc<T>`, implementing [`Aligned`]
+    /// for `Option<Rc<T>>` is safe as well. `Rc` holds [a pointer to its `RcBox` as
+    /// `NonNull<RcBox<T>>`][1]
+    /// And the `Option`-ed type (i.e. `Option<NonNull<RcBox<T>>>`) is explicitly guaranteed
+    /// to be [same as the original type in terms of size and alignment][2].
+    ///
+    /// [1]: https://doc.rust-lang.org/1.81.0/src/alloc/rc.rs.html#315-322
+    /// [2]: https://doc.rust-lang.org/nightly/std/option/index.html#representation
     unsafe impl<T> Aligned for Option<Rc<T>> {
         const ALIGNMENT: usize = max(align_of::<T>(), align_of::<usize>());
     }
 
-    /// It makes assumption on the layout of `Arc`. Use it with caution.
+    /// On top of the safety reasoning of `impl Align for Arc<T>`, implementing [`Aligned`]
+    /// for `Option<Arc<T>>` is safe as well. `Arc` holds [a pointer to its `ArcInner` as
+    /// `NonNull<ArcInner<T>>`][1]
+    /// And the `Option`-ed type (i.e. `Option<NonNull<ArcInner<T>>>`) is explicitly guaranteed
+    /// to be [same as the original type in terms of size and alignment][2].
+    ///
+    /// [1]: https://doc.rust-lang.org/nightly/src/alloc/sync.rs.html#241-248
+    /// [2]: https://doc.rust-lang.org/nightly/std/option/index.html#representation
     unsafe impl<T> Aligned for Option<Arc<T>> {
         const ALIGNMENT: usize = max(align_of::<T>(), align_of::<usize>());
     }