Improve documentation (#3)

* README example

* Add more seriously named function, add docs on usage

* create_stream -> stream_fn

* Fix actions

* Remove cache and cargo-hack for formatter

.github/workflows/tests.yml

@@ -22,6 +22,18 @@ jobs:
       - name: Run checks
         run: cargo hack clippy --feature-powerset --no-dev-deps -- -D warnings
 
+  formatting:
+    name: Formatting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: "nightly"
+          components: "rustfmt"
+      - name: Run checks
+        run: cargo fmt --all -- --check
+
   tests:
     name: Tests
     runs-on: ubuntu-latest
@@ -50,8 +62,12 @@ jobs:
         run: cargo hack miri test --feature-powerset
 
   address-sanitizer:
-    name: Address sanitizer
+    name: "Sanitizer: ${{ matrix.sanitizer }}"
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sanitizer: [address, memory, thread, leak]
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@master
@@ -60,7 +76,10 @@ jobs:
           components: "rust-src"
       - uses: taiki-e/install-action@cargo-hack
       - uses: Swatinem/rust-cache@v2
-      - name: Run tests through address sanitizer
+      - name: "Run tests through ${{ matrix.sanitizer }} sanitizer"
         env:
-          RUSTFLAGS: "-Zrandomize-layout -Zsanitizer=address"
+          ASAN_OPTIONS: "detect_stack_use_after_return=1"
+          RUST_BACKTRACE: "0"
+          RUSTDOCFLAGS: "-Zrandomize-layout -Zsanitizer=${{ matrix.sanitizer }}"
+          RUSTFLAGS: "-Zrandomize-layout -Zsanitizer=${{ matrix.sanitizer }}"
         run: cargo hack test --feature-powerset -Zbuild-std --target x86_64-unknown-linux-gnu

README.md

@@ -17,6 +17,23 @@ Features:
 >
 > While you can't use the yielder inside the unwrapped future, stuff like `embassy` should work again.
 
+## Example
+
+```rust
+use futures_lite::stream;
+use std::pin::pin;
+
+let stream = pin!(asynk_strim::stream_fn(|mut yielder| async move {
+    yielder.yield_item("hello world!").await;
+    yielder.yield_item("pretty neato, ain't it?").await;
+}));
+
+let mut stream = stream::block_on(stream);
+assert_eq!(stream.next(), Some("hello world!"));
+assert_eq!(stream.next(), Some("pretty neato, ain't it?"));
+assert_eq!(stream.next(), None);
+```
+
 ## Comparisons
 
 ### `async-stream`

src/lib.rs

@@ -40,11 +40,48 @@ where
 }
 
 /// Create a new stream
+///
+/// # Example
+///
+/// Let's yield some lyrics (Song: "Verdächtig" by Systemabsturz):
+///
+/// ```
+/// # use futures_lite::StreamExt;
+/// # use std::pin::pin;
+/// # futures_lite::future::block_on(async {
+/// let stream = asynk_strim::stream_fn(|mut yielder| async move {
+///    yielder.yield_item("Fahr den Imsi-Catcher hoch").await;
+///    yielder.yield_item("Mach das Richtmikro an").await;
+///    yielder.yield_item("Bring Alexa auf den Markt").await;
+///    yielder.yield_item("Zapf den Netzknoten an").await;
+///    yielder.yield_item("Fahr den Ü-Wagen vor").await;
+///    yielder.yield_item("Kauf den Staatstrojaner ein").await;
+///    yielder.yield_item("Fake die Exit-Nodes bei Tor").await;
+///    yielder.yield_item("Ihr wollt doch alle sicher sein").await;
+/// });
+///
+/// let mut stream = pin!(stream);
+/// while let Some(item) = stream.next().await {
+///    println!("{item}");
+/// }
+/// # });
 #[inline]
-pub fn strim_fn<F, Item, Fut>(func: F) -> impl Stream<Item = Item>
+pub fn stream_fn<F, Item, Fut>(func: F) -> impl Stream<Item = Item>
 where
     F: FnOnce(Yielder<Item>) -> Fut,
     Fut: Future<Output = ()>,
 {
     crate::stream::init(func)
 }
+
+/// Jokey alias for [`stream_fn`]
+///
+/// For more elaborate documentation, see [`stream_fn`]
+#[inline]
+pub fn strim_fn<F, Item, Fut>(func: F) -> impl Stream<Item = Item>
+where
+    F: FnOnce(Yielder<Item>) -> Fut,
+    Fut: Future<Output = ()>,
+{
+    stream_fn(func)
+}