From 4350b2ddf4f508b3df62500be8cef4bd1d52402e Mon Sep 17 00:00:00 2001
From: Nikita Kniazev <kniazev.nikita@gmail.com>
Date: Sun, 7 Jul 2024 02:03:57 +0300
Subject: [PATCH] Documentation for Clang and Emscripten toolsets

---
 doc/src/reference.adoc    |  3 +++
 src/tools/clang-linux.jam | 10 ++++++++++
 src/tools/clang-win.jam   | 10 ++++++++++
 src/tools/emscripten.jam  | 27 +++++++++++++++++++++++++++
 src/tools/gcc.jam         |  2 +-
 5 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/doc/src/reference.adoc b/doc/src/reference.adoc
index b97bc3809f..b58544fb36 100644
--- a/doc/src/reference.adoc
+++ b/doc/src/reference.adoc
@@ -325,10 +325,13 @@ be used to explicitly request that compiler.
 :leveloffset: +3
 include::../../src/tools/acc.jam[tag=doc]
 include::../../src/tools/borland.jam[tag=doc]
+include::../../src/tools/clang-linux.jam[tag=doc]
+include::../../src/tools/clang-win.jam[tag=doc]
 include::../../src/tools/como.jam[tag=doc]
 include::../../src/tools/cw.jam[tag=doc]
 include::../../src/tools/dmc.jam[tag=doc]
 include::../../src/tools/embarcadero.jam[tag=doc]
+include::../../src/tools/emscripten.jam[tag=doc]
 include::../../src/tools/gcc.jam[tag=doc]
 include::../../src/tools/hp_cxx.jam[tag=doc]
 include::../../src/tools/intel.jam[tag=doc]
diff --git a/src/tools/clang-linux.jam b/src/tools/clang-linux.jam
index 82501f6a88..77bbdd6c5f 100644
--- a/src/tools/clang-linux.jam
+++ b/src/tools/clang-linux.jam
@@ -7,6 +7,16 @@
 #  License Version 1.0. (See accompanying file LICENSE.txt or
 #  https://www.bfgroup.xyz/b2/LICENSE.txt)
 
+#| tag::doc[]
+
+[[bbv2.reference.tools.compiler.clang-linux]]
+= Clang (GCC frontend)
+
+The `clang-linux` module supports Clang with GCC frontend and has the same
+options as link:#bbv2.reference.tools.compiler.gcc[`gcc`] toolset.
+
+|# # end::doc[]
+
 import common ;
 import toolset ;
 import feature ;
diff --git a/src/tools/clang-win.jam b/src/tools/clang-win.jam
index 639a343c26..4d352315d9 100644
--- a/src/tools/clang-win.jam
+++ b/src/tools/clang-win.jam
@@ -5,6 +5,16 @@
 # (See accompanying file LICENSE.txt
 # or copy at https://www.bfgroup.xyz/b2/LICENSE.txt)
 
+#| tag::doc[]
+
+[[bbv2.reference.tools.compiler.clang-win]]
+= Clang (MSVC frontend)
+
+The `clang-win` module supports Clang with MSVC frontend and has the same
+options as link:#bbv2.reference.tools.compiler.msvc[`msvc`] toolset.
+
+|# # end::doc[]
+
 import common ;
 import errors ;
 import feature ;
diff --git a/src/tools/emscripten.jam b/src/tools/emscripten.jam
index 7fa895f598..75f72e9f21 100644
--- a/src/tools/emscripten.jam
+++ b/src/tools/emscripten.jam
@@ -4,6 +4,33 @@
 # (See accompanying file LICENSE.txt
 # or copy at https://www.bfgroup.xyz/b2/LICENSE.txt)
 
+#| tag::doc[]
+
+[[bbv2.reference.tools.compiler.emscripten]]
+= Emscripten
+
+The `emscripten` module supports https://emscripten.org[Emscripten toolchain]
+and has the same options as link:#bbv2.reference.tools.compiler.clang-linux[`clang-linux`]
+toolset.
+
+WARNING: Emscripten toolset defaults to static linkage because it is what
+generally expected and limitations of the toolchain itself
+(`wasm-ld` does not support `rpath`; js launcher does not respect
+`LD_LIBRARY_PATH`/`PATH` when looking for shared objects).
+
+Additional link:#bbv2.overview.invocation.properties[features]
+supported by Emscripten toolset exclusively:
+
+`debug-symbols-source-map`::
+Setting to `on` will enable source map generation, more info could be found in
+https://emscripten.org/docs/tools_reference/emcc.html#emcc-gsource-map[Emscripten documentation].
+
+`exception-handling-method`::
+Setting to `js` will result in using Emscripten’s JavaScript-based exception
+support instead of native WebAssembly exception handling.
+
+|# # end::doc[]
+
 import feature ;
 import os ;
 import toolset ;
diff --git a/src/tools/gcc.jam b/src/tools/gcc.jam
index b7825d4e60..0c69dbdb72 100644
--- a/src/tools/gcc.jam
+++ b/src/tools/gcc.jam
@@ -14,7 +14,7 @@
 #| tag::doc[]
 
 [[bbv2.reference.tools.compiler.gcc]]
-= GNU C++
+= GCC - GNU Compiler Collection
 
 The `gcc` module supports the http://gcc.gnu.org[GNU C++ compiler] on
 Linux, a number of Unix-like system including SunOS and on Windows