diff options
| -rw-r--r-- | docs/InternalsManual.html | 31 |
1 files changed, 21 insertions, 10 deletions
diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index 89111dac47..2497cc67a6 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -161,20 +161,31 @@ produce diagnostics to tell the user their code is non-portable. The difference is that the former are ignored by default, and the later warn by default. The <tt>WARNING</tt> severity is used for constructs that are valid in the currently selected source language but that are dubious in some way. The <tt>NOTE</tt> -level is used to staple more information onto a previous diagnostics.</p> +level is used to staple more information onto a previous diagnostics. <p>These <em>severities</em> are mapped into a smaller set (the Diagnostic::Level enum, {<tt>Ignored</tt>, <tt>Note</tt>, <tt>Warning</tt>, <tt>Error</tt>, <tt>Fatal</tt> }) of output <em>levels</em> by the diagnostics -subsystem based -on various configuration options. For example, if the user specifies -<tt>-pedantic</tt>, <tt>EXTENSION</tt> maps to <tt>Warning</tt>, if they specify -<tt>-pedantic-errors</tt>, it turns into <tt>Error</tt>. Clang also internally -supports a fully fine grained mapping mechanism that allows you to map any -diagnostic that doesn't have <tt>ERRROR</tt> severity to any output level that -you want. This is used to implement options like <tt>-Wunused_macros</tt>, -<tt>-Wundef</tt> etc. Fatal errors are considered so severe that diagnostics -that occur after them are supressed as "almost certainly useless".</p> +subsystem based on various configuration options. Clang internally supports a +fully fine grained mapping mechanism that allows you to map almost any +diagnostic to the output level that you want. The only diagnostics that cannot +be mapped are <tt>NOTE</tt>s, which always follow the severity of the previously +emitted diagnostic and <tt>ERROR</tt>s, which can only be mapped to +<tt>Fatal</tt> (it is not possible to turn an error into a warning, +for example).</p> + +<p>Diagnostic mappings are used in many ways. For example, if the user +specifies <tt>-pedantic</tt>, <tt>EXTENSION</tt> maps to <tt>Warning</tt>, if +they specify <tt>-pedantic-errors</tt>, it turns into <tt>Error</tt>. This is +used to implement options like <tt>-Wunused_macros</tt>, <tt>-Wundef</tt> etc. +</p> + +<p> +Mapping to <tt>Fatal</tt> should only be used for diagnostics that are +considered so severe that error recovery won't be able to recover sensibly from +them (thus spewing a ton of bogus errors). One example of this class of error +are failure to #include a file. +</p> <!-- ================= --> <h4>The Format String</h4> |