irc: Explain the benefits in the doc

Author: frostyplanet

README.md

@@ -23,7 +23,7 @@ This crate provides two categories of modules:
       - std `Box` (owned),
       - std `Arc`, `Rc` (multiple ownership)
       - [Irc](https://docs.rs/embed-collections/latest/embed_collections/irc/): Highly customized Intrusive Reference Counter. See the detail in
-      module doc.
+        module doc.
       - [WaitGroupZeroGuard](https://docs.rs/crossfire/latest/crossfire/waitgroup/struct.WaitGroupZeroGuard.html):  see the doc in `crossfire` crate
       - raw pointers (`NonNull<T>`, `*const T`, `*mut T`)
     - Structs:
@@ -32,7 +32,6 @@ This crate provides two categories of modules:
       - [slist_owned](https://docs.rs/embed-collections/latest/embed_collections/slist_owned/): An intrusive slist but with safe and more compact interface
       - [avl](https://docs.rs/embed-collections/latest/embed_collections/avl/): Intrusive AVL Tree (Balanced Binary Search Tree), port to rust from ZFS
 
-
 **Disclaimer**
 
 Intrusive code is not recommended unless you are full aware of what you are doing.
@@ -151,7 +150,7 @@ There're three usage scenarios:
 
 2. Push `Box` to the list, the list own the items until they are popped, it's better than std
    LinkedList because no additional allocation is needed.  It will not move the item
-   in-and-out of hidden `Box` on every push / pop.  
+   in-and-out of hidden `Box` on every push / pop.
 
 3. Push raw pointer (better use NonNull instead of *const T for smaller footprint) to the list,
    for temporary usage. You must ensure the list item not dropped be other refcount

src/irc.rs

@@ -6,9 +6,27 @@
 //! The underlayer of `Irc` is Box, unlike `Arc` which wrap a hidden ArcInner on your inner types,
 //! Irc use the same memory location of your inner types.
 //!
-//! [IrcItem::on_drop] in the trait allow you to have the ownship of underlying inner memory after the reference count of Irc is dropped.
+//! # Benefits
 //!
-//! # Example
+//! - No need to manual implementing the inc / dec on counter.
+//!
+//! - No enforced weak counter if you don't need it (every atomic op has cost).
+//!
+//! - [IrcItem::on_drop] in the trait allow you to have the ownship of underlying inner memory after
+//!   the reference count of Irc is dropped. And you only need to define the drop behavior once,
+//!   instead of write the same logic `Arc::into_inner` in every possible places
+//!   (If forgetting so make your code block and hard to debug).
+//!
+//! - Using `Irc` to wrap a `Box`, no additional memory allocation and memory fragmentation, no
+//!   additional dereference cost (than using `Arc<Box<T>>`)
+//!
+//! - You can allocate a box from the time of its birth and wrap it will `Irc` for temporary usage,
+//!   don't need to move bytes from / to stack. (especially when the inner object is large)
+//!
+//! - Advanced usage, multiple layer customized counter, on the same heap object, while preserving
+//!   the safe boundary
+//!
+//! # Example (Irc wrapping a Box)
 //!
 //! ```rust
 //! use embed_collections::irc::{Irc, IrcItem};

src/lib.rs

@@ -21,7 +21,7 @@
 //!       - std `Box` (owned),
 //!       - std `Arc`, `Rc` (multiple ownership)
 //!       - [Irc](crate::irc): Highly customized Intrusive Reference Counter. See the detail in
-//!       module doc.
+//!         module doc.
 //!       - [WaitGroupZeroGuard](https://docs.rs/crossfire/latest/crossfire/waitgroup/struct.WaitGroupZeroGuard.html):  see the doc in `crossfire` crate
 //!       - raw pointers (`NonNull<T>`, `*const T`, `*mut T`)
 //!     - Structs:
@@ -148,7 +148,7 @@
 //!
 //! 2. Push `Box` to the list, the list own the items until they are popped, it's better than std
 //!    LinkedList because no additional allocation is needed.  It will not move the item
-//!    in-and-out of hidden `Box` on every push / pop.  
+//!    in-and-out of hidden `Box` on every push / pop.
 //!
 //! 3. Push raw pointer (better use NonNull instead of *const T for smaller footprint) to the list,
 //!    for temporary usage. You must ensure the list item not dropped be other refcount