From e3a9b1f62eeed6d22ba7cb89c1ca94cfc9bb410f Mon Sep 17 00:00:00 2001
From: Anton Parfonov <antonparfonov@gmail.com>
Date: Wed, 27 Mar 2024 12:49:21 +0200
Subject: [PATCH] Doc update

---
 module/core/collection_tools/Readme.md  | 43 ++++++++++++++++++++++++-
 module/core/collection_tools/src/lib.rs |  8 ++++-
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/module/core/collection_tools/Readme.md b/module/core/collection_tools/Readme.md
index 3c333f79be..8bc6ed0524 100644
--- a/module/core/collection_tools/Readme.md
+++ b/module/core/collection_tools/Readme.md
@@ -24,12 +24,43 @@ let meta_map = hmap! { 3 => 13 };
 let mut std_map = collection_tools::HashMap::new();
 std_map.insert( 3, 13 );
 assert_eq!( meta_map, std_map );
-
 # }
 ```
 
 Note: Do not be afraid of `collection_tools::HashMap`. It is basically a reexport of `std`'s `HashMap`, unless you have enabled `use_alloc` feature.
 
+Another example, this time, `bset!`, providing you a `BTreeSet`:
+
+```rust
+# #[ cfg( all( feature = "enabled", feature = "collection_constructors" ) ) ]
+# #[ cfg( any( feature = "use_alloc", not( feature = "no_std" ) ) ) ]
+# {
+use collection_tools::*;
+
+let meta_set = bset! { 3, 13 };
+let mut std_set = collection_tools::BTreeSet::new();
+std_set.insert( 13 );
+std_set.insert( 3 );
+assert_eq!( meta_set, std_set );
+# }
+```
+
+Another example with `list!`:
+
+```rust
+# #[ cfg( all( feature = "enabled", feature = "collection_constructors" ) ) ]
+# #[ cfg( any( feature = "use_alloc", not( feature = "no_std" ) ) ) ]
+# {
+use collection_tools::*;
+
+let meta_list : LinkedList< i32 > = list! { 3, 13 };
+let mut meta_list = collection_tools::LinkedList::new();
+meta_list.push_front( 13 );
+meta_list.push_front( 3 );
+assert_eq!( meta_list, meta_list );
+# }
+```
+
 ### Basic Use Case :: `no_std` `HashSet` / `HashMap`
 
 When implementing a `no_std` environment with the `use_alloc` feature in your Rust project, you'll encounter a challenge: collections like `Vec` are imported differently depending on the availability of the `std` library. Moreover, to use data structures such as `HashSet` or `HashMap` in a `no_std` context, it's necessary to depend on third-party crates, as these are not provided by the `alloc` crate directly. This crate aims to simplify the process of designing Rust libraries or applications that require these collections in a `no_std` environment, offering a more streamlined approach to working with dynamic data structures without the standard library.
@@ -67,6 +98,16 @@ assert_eq!( vec.contains( &1 ), true );
 
 </details>
 
+### Collections being used
+
+To support `no_std` environment as much as possible, we aim at using collections from `alloc` whenever its possible.
+
+If `use_alloc` feature is on, collections available only in `std` are replaced with their `no_std` counterparts. For now, the only replaced collections are `HashMap` and `HashSet` , taken from `hashbrown`.
+
+### MORE Examples
+
+If you are feeling confused about the syntax you should use for a macro, you can visit its documentation. It is saturated with different examples, so hopefully you'll not be stuck.
+
 ### To add to your project
 
 ```sh
diff --git a/module/core/collection_tools/src/lib.rs b/module/core/collection_tools/src/lib.rs
index 43f001f147..834304f7ca 100644
--- a/module/core/collection_tools/src/lib.rs
+++ b/module/core/collection_tools/src/lib.rs
@@ -29,8 +29,14 @@ pub mod protected
   pub use super::orphan::*;
 
   extern crate alloc;
+  #[ doc( inline ) ]
+  #[ allow( unused_imports ) ]
   pub use alloc::vec;
+  #[ doc( inline ) ]
+  #[ allow( unused_imports ) ]
   pub use alloc::vec::Vec;
+  #[ doc( inline ) ]
+  #[ allow( unused_imports ) ]
   pub use alloc::collections::{ BinaryHeap, BTreeMap, BTreeSet, LinkedList, VecDeque };
   #[ cfg( feature = "use_alloc" ) ]
   #[ doc( inline ) ]
@@ -70,7 +76,7 @@ pub mod prelude
   pub use super::constructors::*;
 }
 
-/// Macros used in `use_alloc` context
+/// Macros to construct the collections.
 /// Basically a tweaked version of `literally` crate but using `alloc` / `hashbrown` instead of `std`
 #[ cfg( all( feature = "enabled", feature = "collection_constructors" ) ) ]
 pub mod constructors;
\ No newline at end of file