Improve wasm explanation in Cargo.toml

Cargo.toml

@@ -24,24 +24,38 @@ profiling = { version = "1" }
 tracing = { version = "0.1.40", optional = true }
 aligned-vec = "0.5.0"
 
-# Note: We need to differentiate between wasm32-unknown-unknown and
-# wasm32-wasi. cfg(target_arch = "wasm32") will match both.
+[[bench]]
+name = "bench"
+harness = false
 
-# We need to disable the default "rayon" feature on wasm32.
+#
+# WebAssembly/wasm32 target support below
+#
+# There are two main WASM targets:
+# - wasm32-unknown-unknown: Base WebAssembly standard, used in browsers
+# - wasm32-wasi: Newer extension/standard, comes with basic std library,
+#   not supported in browsers (yet)
+#
+# Some things work in all WASM configurations, some work only on one of these two,
+# some things don't work on wasm32 at all.
+#
+# wasm32-unknown-unknown requires wasm_bindgen and wasm_bindgen_test to work,
+# but these can cause problems on wasm32-wasi. So we use either
+# - target_arch = "wasm32" for things that (don't) work on all WebAssembly targets or
+# - explicit targetting for wasm32-unknown-unknown or wasm32-wasi.
+#   In Cargo.toml, this is done via [target.<target-triple>.dependencies]
+#   In code, this is done via cfg(all(target_arch = "wasm32", target_os = "wasi"/"unknown"))
+
+# The rayon feature does not work on any wasm32 target
 [target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
 criterion = "0.5"
 
 [target.'cfg(target_arch = "wasm32")'.dev-dependencies]
 criterion = { version = "0.5", default-features = false }
 
-# wasm-bindgen is needed for wasm32-unknown-unknown, but not
-# for wasm32-wasi.
+# wasm-bindgen is only needed for wasm32-unknown-unknown and not other wasm32 targets
 [target.wasm32-unknown-unknown.dependencies]
 wasm-bindgen = "0.2"
 
 [target.wasm32-unknown-unknown.dev-dependencies]
 wasm-bindgen-test = "0.3"
-
-[[bench]]
-name = "bench"
-harness = false