r367889 - [docs] document -Weveything more betterer

[JF Bastien via cfe-commits]

Author: jfb
Date: Mon Aug  5 09:53:45 2019
New Revision: 367889

URL: http://llvm.org/viewvc/llvm-project?rev=367889&view=rev
Log:
[docs] document -Weveything more betterer

Reviewers: aaron.ballman

Subscribers: jkorous, dexonsmith, cfe-commits

Tags: #clang

Differential Revision: https://reviews.llvm.org/D65706

Modified:
    cfe/trunk/docs/UsersManual.rst

Modified: cfe/trunk/docs/UsersManual.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=367889&r1=367888&r2=367889&view=diff
==============================================================================
--- cfe/trunk/docs/UsersManual.rst (original)
+++ cfe/trunk/docs/UsersManual.rst Mon Aug  5 09:53:45 2019
@@ -992,13 +992,24 @@ is treated as a system header.
 Enabling All Diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In addition to the traditional ``-W`` flags, one can enable **all**
-diagnostics by passing :option:`-Weverything`. This works as expected
-with
-:option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
+In addition to the traditional ``-W`` flags, one can enable **all** diagnostics
+by passing :option:`-Weverything`. This works as expected with
+:option:`-Werror`, and also includes the warnings from :option:`-pedantic`. Some
+diagnostics contradict each other, therefore, users of :option:`-Weverything`
+often disable many diagnostics such as :option:`-Wno-c++98-compat`
+:option:`-Wno-c++-compat` because they contradict recent C++ standards.
 
-Note that when combined with :option:`-w` (which disables all warnings), that
-flag wins.
+Since :option:`-Weverything` enables every diagnostic, we generally don't
+recommend using it. :option:`-Wall` :option:`-Wextra` are a better choice for
+most projects. Using :option:`-Weverything` means that updating your compiler is
+more difficult because you're exposed to experimental diagnostics which might be
+of lower quality than the default ones. If you do use :option:`-Weverything`
+then we advise that you address all new compiler diagnostics as they get added
+to Clang, either by fixing everything they find or explicitly disabling that
+diagnostic with its corresponding `Wno-` option.
+
+Note that when combined with :option:`-w` (which disables all warnings),
+disabling all warnings wins.
 
 Controlling Static Analyzer Diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^