doc: Be more specific about warning_level option

Fixes: #11469

1 files changed, 17 insertions, 0 deletions

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index f8c3d8a..f8e94a8 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -95,6 +95,8 @@ machine](#specifying-options-per-machine) section for details.
 | wrap_mode {default, nofallback,<br>nodownload, forcefallback, nopromote} | default | Wrap mode to use                 | no             | no                |
 | force_fallback_for                     | []            | Force fallback for those dependencies                          | no             | no                |
 
+#### Details for `buildtype`
+
 <a name="build-type-options"></a> For setting optimization levels and
 toggling debug, you can either set the `buildtype` option, or you can
 set the `optimization` and `debug` options which give finer control
@@ -113,6 +115,21 @@ the two-way mapping:
 
 All other combinations of `debug` and `optimization` set `buildtype` to `'custom'`.
 
+#### Details for `warning_level`
+
+Exact flags per warning level is compiler specific, but there is an approximative
+table for most common compilers.
+
+| Warning level | GCC/Clang                | MSVC  |
+| ------------- | ---                      | ----  |
+| 0             |                          |       |
+| 1             | -Wall                    | /W2   |
+| 2             | -Wall -Wextra            | /W3   |
+| 3             | -Wall -Wextra -Wpedantic | /W4   |
+| everything    | -Weverything             | /Wall |
+
+Clang's `-Weverything` is emulated on GCC by passing all known warning flags.
+
 ## Base options
 
 These are set in the same way as universal options, either by