Extend description of Emscripten and contrast with other WASM targets

Co-authored-by: Alex Crichton <[email protected]>

Author: juntyr

src/doc/rustc/src/platform-support/wasm32-unknown-emscripten.md

@@ -3,33 +3,36 @@
 **Tier: 2**
 
 The `wasm32-unknown-emscripten` target is a WebAssembly compilation target which
-uses the [Emscripten](https://emscripten.org/) compiler toolchain. Unlike the
-[`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md) target, which only has
-partial support for the Rust standard library, `wasm32-unknown-emscripten`
-integrates with JavaScipt on the web to provide a more featureful standard library.
-This target is often used when compiling for the web, accessing web APIs, or
-interoperating with C and C++ code.
+uses the [Emscripten](https://emscripten.org/) compiler toolchain. Emscripten is
+a C/C++ toolchain used for running C/C++ code on the web. It provides POSIX `libc`
+and `libstd` implementations, access to the OpenGL and SDL APIs, and the ability
+to run arbitrary JavaScript code, all based on web APIs using JS glue code. With
+the `wasm32-unknown-emscripten` target, Rust code can interoperate with
+Emscripten's ecosystem, C/C++ and JS code, and web APIs.
 
 One existing user of this target is the
 [`pyodide` project](https://pyodide.org/) which provides a Python runtime in
 WebAssembly using Emscripten and compiles Python extension modules written in Rust
 to the `wasm32-unknown-emscripten` target.
 
-If you want to target the web but no not need interop with C/C++ or you want to
-produce a bare-bones WebAssembly binary and you do not require access to the host
-environment (e.g. stdio, file access, networking, etc.), consider using the
-[`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md) target instead.
-
-If you need access to the host environment, consider using one of the WASI targets
-([`wasm32-wasip1`](./wasm32-wasip1.md) or [`wasm32-wasip2`](./wasm32-wasip2.md)).
+If you want to generate a standalone bare-bones WebAssembly binary that does not
+require JS glue code and access to the web APIs and can thus run outside the web,
+the [`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md) target may be better
+suited for you. However, [`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md)
+only has partial support for the Rust standard library and does not (easily)
+support interop with C/C++ code.
+
+Like Emscripten, the WASI targets [`wasm32-wasip1`](./wasm32-wasip1.md) and
+[`wasm32-wasip2`](./wasm32-wasip2.md) also provide access to the host environment,
+support interop with C/C++ (and other languages), and support most of the Rust
+standard library. While the WASI targets are portable across different hosts
+(web and non-web), WASI has no standard way of accessing web APIs, whereas
+Emscripten has the ability to run arbitrary JS from WASM and access many web APIs.
+If you are only targeting the web and need to access web APIs, the
+`wasm32-unknown-emscripten` target may be preferable.
 
 ## Target maintainers
 
-When this target was added to the compiler, platform-specific documentation here
-was not maintained at that time. This means that the list below is not
-exhaustive, and there are more interested parties in this target. That being
-said, those interested in maintaining this target are:
-
 - Hood Chatham, https://github.com/hoodmane
 - Sam Clegg, https://github.com/sbc100
 - Juniper Tyree, https://github.com/juntyr
@@ -99,11 +102,15 @@ It's recommended to conditionally compile code for this target with:
 #[cfg(all(target_family = "wasm", target_os = "emscripten"))]
 ```
 
-Note that there is no way to tell via `#[cfg]` whether code will be running on
-the web or not.
-
 ## Enabled WebAssembly features
 
 WebAssembly is an evolving standard which adds new features such as new
-instructions over time. The `wasm32-unknown-emscripten` target inherits the
-default settings of Emscripten.
+instructions over time. This target's default set of supported WebAssembly
+features will additionally change over time. The `wasm32-unknown-emscripten` target
+inherits the default settings of LLVM which typically, but not necessarily, matches
+the default settings of Emscripten as well.
+
+Please refer to the [`wasm32-unknown-unknown`](./wasm32-unknown-unknown.md)
+target's documentation on which WebAssembly features Rust enables by default, how
+features can be disabled, and how Rust code can be conditionally compiled based on
+which features are enabled.