Improve readability of README (markdown doesn't support hidden code like rustdoc)

Author: paberr

README.md

@@ -32,7 +32,7 @@ This is useful for users that do not want a direct serde dependency. Internally,
 
 You can then start using the library without further setup.
 If you plan on using the global `WebWorkerPool` (using the iterator extensions or `worker_pool()`), you can *optionally* configure this pool:
-```rust,no_run
+```rust
 // Importing it publicly will also expose the function on the JavaScript side.
 // You can instantiate the pool both via Rust and JS.
 pub use wasmworker::{init_worker_pool, WorkerPoolOptions};
@@ -42,7 +42,6 @@ async fn startup() {
     options.num_workers = Some(2); // Default is navigator.hardwareConcurrency
     init_worker_pool(options).await.expect("Worker pool already initialized");
 }
-# fn main() {}
 ```
 
 ### Outsourcing tasks
@@ -52,11 +51,12 @@ The library offers three ways of outsourcing function calls onto concurrent work
 3. `par_map`: an extension to regular iterators, which allows to execute a function on every element of the iterator in parallel using the default worker pool.
 
 All approaches require the functions that should be executed to be annotated with the `#[webworker_fn]` macro.
-This macro ensures that the functions are available to the web worker instances:
+This macro ensures that the functions are available to the web worker instances.
+To execute such a function, pass its `WebWorkerFn` handle (obtained via the `webworker!()` macro) to a worker:
 
-```rust,no_run
+```rust
 use serde::{Deserialize, Serialize};
-use wasmworker::webworker_fn;
+use wasmworker::{webworker, webworker_fn};
 
 /// An arbitrary type that is (de)serializable.
 #[derive(Serialize, Deserialize)]
@@ -68,65 +68,52 @@ pub fn sort_vec(mut v: VecType) -> VecType {
     v.0.sort();
     v
 }
-# fn main() {}
-```
-
-Whenever we want to execute a function, we need to pass the corresponding `WebWorkerFn` object to the worker.
-This object describes the function to the worker and can be safely obtained via the `webworker!()` macro:
 
-```rust,no_run
-# use serde::{Deserialize, Serialize};
-# use wasmworker::webworker_fn;
-# #[derive(Serialize, Deserialize)]
-# pub struct VecType(Vec<u8>);
-# #[webworker_fn]
-# pub fn sort_vec(mut v: VecType) -> VecType { v.0.sort(); v }
-use wasmworker::webworker;
-
-# fn main() {
+// Obtain a type-safe handle to the function:
 let ww_sort = webworker!(sort_vec);
-# }
 ```
 
 #### WebWorker
 We can instantiate our own workers and run functions on them:
-```rust,no_run
-# use serde::{Deserialize, Serialize};
-# use wasmworker::webworker_fn;
-# #[derive(Serialize, Deserialize, PartialEq, Debug)]
-# pub struct VecType(Vec<u8>);
-# #[webworker_fn]
-# pub fn sort_vec(mut v: VecType) -> VecType { v.0.sort(); v }
-use wasmworker::{webworker, WebWorker};
-
-# async fn example() {
+```rust
+use serde::{Deserialize, Serialize};
+use wasmworker::{webworker, webworker_fn, WebWorker};
+
+#[derive(Serialize, Deserialize)]
+pub struct VecType(Vec<u8>);
+
+#[webworker_fn]
+pub fn sort_vec(mut v: VecType) -> VecType {
+    v.0.sort();
+    v
+}
+
 let worker = WebWorker::new(None).await.expect("Couldn't create worker");
-let res = worker.run(webworker!(sort_vec), &VecType(vec![5, 2, 8])).await;
-assert_eq!(res.0, vec![2, 5, 8]);
-# }
-# fn main() {}
+let sorted = worker.run(webworker!(sort_vec), &VecType(vec![3, 1, 2])).await;
+assert_eq!(sorted.0, vec![1, 2, 3]);
 ```
 
 #### WebWorkerPool
 Most of the time, we probably want to schedule tasks to a pool of workers, though.
 The default worker pool is instantiated on first use and can be configured using `init_worker_pool()` as described above.
 It uses a round-robin scheduler (with the second option being a load based scheduler), a number of `navigator.hardwareConcurrency` separate workers, and the default inferred path.
 
-```rust,no_run
-# use serde::{Deserialize, Serialize};
-# use wasmworker::webworker_fn;
-# #[derive(Serialize, Deserialize, PartialEq, Debug)]
-# pub struct VecType(Vec<u8>);
-# #[webworker_fn]
-# pub fn sort_vec(mut v: VecType) -> VecType { v.0.sort(); v }
-use wasmworker::{webworker, worker_pool};
+```rust
+use serde::{Deserialize, Serialize};
+use wasmworker::{webworker, webworker_fn, worker_pool};
+
+#[derive(Serialize, Deserialize)]
+pub struct VecType(Vec<u8>);
+
+#[webworker_fn]
+pub fn sort_vec(mut v: VecType) -> VecType {
+    v.0.sort();
+    v
+}
 
-# async fn example() {
 let worker_pool = worker_pool().await;
-let res = worker_pool.run(webworker!(sort_vec), &VecType(vec![5, 2, 8])).await;
-assert_eq!(res.0, vec![2, 5, 8]);
-# }
-# fn main() {}
+let sorted = worker_pool.run(webworker!(sort_vec), &VecType(vec![3, 1, 2])).await;
+assert_eq!(sorted.0, vec![1, 2, 3]);
 ```
 
 #### Iterator extension
@@ -242,34 +229,27 @@ No Rust-side changes are needed — `import.meta.url` resolves correctly when th
 If your build setup places the wasm-bindgen glue or WASM binary at non-standard locations
 (e.g., hashed filenames, nested directories), you can override the paths explicitly:
 
-```rust,no_run
+```rust
 use wasmworker::{init_worker_pool, WorkerPoolOptions};
 
-# async fn example() -> Result<(), wasmworker::AlreadyInitialized> {
 let mut options = WorkerPoolOptions::new();
 // Path to the wasm-bindgen glue file (used by worker blob's import())
 options.path = Some("/assets/myapp.js".to_string());
 // Path to the WASM binary (passed to wasm-bindgen's init function)
 options.path_bg = Some("/assets/myapp_bg.wasm".to_string());
-init_worker_pool(options).await?;
-# Ok(())
-# }
-# fn main() {}
+init_worker_pool(options).await.unwrap();
 ```
 
 #### Precompiling WASM
 
 To reduce bandwidth (fetch WASM once instead of once per worker), you can precompile and share the module:
 
-```rust,no_run
-# use wasmworker::{init_worker_pool, WorkerPoolOptions};
-# async fn example() -> Result<(), wasmworker::AlreadyInitialized> {
+```rust
+use wasmworker::{init_worker_pool, WorkerPoolOptions};
+
 let mut options = WorkerPoolOptions::new();
 options.precompile_wasm = Some(true);
-init_worker_pool(options).await?;
-# Ok(())
-# }
-# fn main() {}
+init_worker_pool(options).await.unwrap();
 ```
 
 ## FAQ

src/lib.rs

@@ -1,4 +1,99 @@
-#![doc = include_str!("../README.md")]
+//! # wasmworker
+//!
+//! Parallelize tasks on WebAssembly without `SharedArrayBuffer`.
+//!
+//! See the [README](https://github.com/paberr/wasmworker) for full documentation
+//! including bundler setup and FAQ.
+//!
+//! ## Quick start
+//!
+//! Add to your `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! wasmworker = { version = "0.2", features = ["macros"] }
+//! ```
+//!
+//! ### Defining worker functions
+//!
+//! ```no_run
+//! use serde::{Deserialize, Serialize};
+//! use wasmworker::{webworker, webworker_fn};
+//!
+//! /// An arbitrary type that is (de)serializable.
+//! #[derive(Serialize, Deserialize)]
+//! pub struct VecType(Vec<u8>);
+//!
+//! /// A sort function on a custom type.
+//! #[webworker_fn]
+//! pub fn sort_vec(mut v: VecType) -> VecType {
+//!     v.0.sort();
+//!     v
+//! }
+//!
+//! # fn main() {
+//! // Obtain a type-safe handle to the function:
+//! let ww_sort = webworker!(sort_vec);
+//! # }
+//! ```
+//!
+//! ### Running tasks
+//!
+//! ```no_run
+//! # use serde::{Deserialize, Serialize};
+//! # use wasmworker::{webworker, webworker_fn, WebWorker};
+//! #
+//! # #[derive(Serialize, Deserialize, PartialEq, Debug)]
+//! # pub struct VecType(Vec<u8>);
+//! #
+//! # #[webworker_fn]
+//! # pub fn sort_vec(mut v: VecType) -> VecType {
+//! #     v.0.sort();
+//! #     v
+//! # }
+//! #
+//! # async fn example() {
+//! let worker = WebWorker::new(None).await.expect("Couldn't create worker");
+//! let sorted = worker.run(webworker!(sort_vec), &VecType(vec![3, 1, 2])).await;
+//! assert_eq!(sorted.0, vec![1, 2, 3]);
+//! # }
+//! # fn main() {}
+//! ```
+//!
+//! ```no_run
+//! # use serde::{Deserialize, Serialize};
+//! # use wasmworker::{webworker, webworker_fn, worker_pool};
+//! #
+//! # #[derive(Serialize, Deserialize, PartialEq, Debug)]
+//! # pub struct VecType(Vec<u8>);
+//! #
+//! # #[webworker_fn]
+//! # pub fn sort_vec(mut v: VecType) -> VecType {
+//! #     v.0.sort();
+//! #     v
+//! # }
+//! #
+//! # async fn example() {
+//! let worker_pool = worker_pool().await;
+//! let sorted = worker_pool.run(webworker!(sort_vec), &VecType(vec![3, 1, 2])).await;
+//! assert_eq!(sorted.0, vec![1, 2, 3]);
+//! # }
+//! # fn main() {}
+//! ```
+//!
+//! ### Configuring the worker pool
+//!
+//! ```no_run
+//! # use wasmworker::{init_worker_pool, WorkerPoolOptions};
+//! #
+//! # async fn startup() {
+//! let mut options = WorkerPoolOptions::new();
+//! options.num_workers = Some(2); // Default is navigator.hardwareConcurrency
+//! init_worker_pool(options).await.expect("Worker pool already initialized");
+//! # }
+//! # fn main() {}
+//! ```
+
 #![allow(clippy::borrowed_box)]
 pub use channel::Channel;
 pub use channel_task::ChannelTask;