From 2ee9e8e82f44c9c3d904956eed0e6c1dfa968db6 Mon Sep 17 00:00:00 2001
From: polazarus <polazarus@users.noreply.github.com>
Date: Sun, 10 Nov 2024 15:33:53 +0100
Subject: [PATCH] chore: improve README

---
 README.md | 39 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 34 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 9322df1..8cad72f 100644
--- a/README.md
+++ b/README.md
@@ -34,19 +34,31 @@ let chars = user.chars().count(); // "inherits" `&str` methods
 
 ## ✏️ Features
 
-- `std` (default): uses `std` rather than `core` and `alloc`, and also provides more trait implementations (for comparison, conversions, and errors)
+- `std` (default): uses `std` rather than `core` and `alloc`, and also provides more trait implementations (for comparison and conversions)
 - `serde`: provides serialization/deserialization support with `serde` crate
 - `unstable`: exposes internal `Backend` trait that may change at any moment
 
 ## ☣️ Safety of `hipstr`
 
-This crate uses `unsafe` extensively. 🤷
+This crate makes extensive use of `unsafe` code blocks. 🤷
 
-It exploits the 2-bit alignment niche in pointers existing on most platforms (I think all Rustc supported platforms) to distinguish the inline representation from the other representations.
+It leverages the 2-bit alignment niche present in pointers across most platforms (all platforms currently supported by the Rust compiler?) to discriminate between the three possible representations.
 
 To make things safer, Rust is tested thoroughly on multiple platforms, normally and with [Miri] (the MIR interpreter).
 
-## 🧪 Testing
+## 🧪 Testing and Verification Strategy
+
+To ensure safety and reliability, this crate undergoes thorough testing:
+
+- Near 100% test coverage
+- Cross-platform validation:
+  - 32-bit and 64-bit architectures
+  - little and big endian
+
+In addition, this crate is checked with advanced dynamic verification methods:
+
+- Concurrency testing using the [Tokio's loom crate][loom]
+- Undefined behavior detection using [Miri] (the MIR interpreter)
 
 ### ☔ Coverage
 
@@ -64,6 +76,12 @@ Check out the current coverage on [Codecov]:
 
 ### 🖥️ Cross-platform testing
 
+In the Github-provided CI, `hipstr` is tested under:
+
+- Linux
+- Windows
+- MacOS (ARM 64-bit LE)
+
 You can easily run the test on various platforms with [`cross`]:
 
 ```bash
@@ -75,6 +93,14 @@ cross test --target x86_64-unknown-linux-gnu        # 64-bit LE
 
 NB: previously I used MIPS targets for big endian, but due to some LLVM-related issue they are not working anymore… see [Rust issue #113065](https://github.com/rust-lang/rust/issues/113065)
 
+### 🧵 [Loom]
+
+This crates uses the `loom` crate to check the custom "Arc" implementation. To run the tests:
+
+```bash
+RUSTFLAGS='--cfg loom' cargo test --release loom
+```
+
 ### 🔍 [Miri]
 
 This crate runs successfully with Miri:
@@ -97,6 +123,8 @@ cargo +nightly miri test --target mips64-unknown-linux-gnuabi64
 cargo +nightly miri test --target i686-unknown-linux-gnu
 ```
 
+Note: this crate leverages the "exposed provenance" semantics.
+
 ## 📦 Similar crates
 
 `#[non_exhaustive]`
@@ -121,7 +149,7 @@ skipping specialized string types like [`tinystr`](https://github.com/unicode-or
 
 In short, `HipStr`, one string type to rule them all 😉
 
-[![How standards proliferate](https://imgs.xkcd.com/comics/standards.png)](https://xkcd.com/927/)
+[![How standards proliferate](https://imgs.xkcd.com/comics/standards.png)](https://xkcd.com/927/ )
 
 ## 🏎️ Performances
 
@@ -139,3 +167,4 @@ MIT + Apache
 [codecov]: https://app.codecov.io/gh/polazarus/hipstr
 [miri]: https://github.com/rust-lang/miri
 [`cross`]: https://github.com/cross-rs/cross
+[loom]: https://github.com/tokio-rs/loom
\ No newline at end of file