[docs] Better documentation for -Weverything

[lebedev.ri]

clang/docs/UsersManual.rst

998

users *of*

[jfb]

• Missing 'of'

[aaron.ballman]

Thank you for working on this!

clang/docs/UsersManual.rst

998

users of -Weverything therefore -> therefore, users of -Weverything

999–1000

Would you care to propose a more exhaustive list of conflicting diagnostics? (Perhaps in a follow-up patch.)

1006

once -> ones
Add a comma after -Weverything

1008

clang -> Clang

[jfb]

• Address Aaron's comments.

clang/docs/UsersManual.rst

999–1000

I looked a bit and I'm worried that providing a list won't be particularly satisfying for people looking at this. I think it's better to have some warning, and let folks figure out what works for their particular situation. Here I'm assuming that they don't use C++98 and that seems reasonable, but figuring out what side of contradictions they're on doesn't seem like it'll work out.

[aaron.ballman]

clang/docs/UsersManual.rst

999–1000

One of the primary concerns with enabling -Weverything is the fact that we know this enables conflicting diagnostics. Telling the user "we know there are conflicting diagnostics, but we want you to have the joy of figuring out which ones conflict for yourself" seems even more unsatisfying, to me. I agree that we don't want to tell users which of the conflicting options they should disable, but was thinking of something more along the lines of:

The following sets of options are known to have some possibly unfortunate interactions when enabled together:
  * -Wfoo, -Wbar
  * -Wbaz, -Wquux
  * ...
Note that there may be other conflicting diagnostic flags not listed above.

I figure that gives users a bit more of an idea of what they're signing up for when they enable -Weverything, which seems useful.

[jfb]

clang/docs/UsersManual.rst

999–1000

OK I can do that as a follow-up.

[aaron.ballman]

LGTM!

clang/docs/UsersManual.rst

999–1000

Awesome, thank you!

[xbolva00]

This comment was removed by xbolva00.

clang/docs/UsersManual.rst

 directory is treated as including a system header if the including file
 is treated as a system header.
 
 .. _diagnostics_enable_everything:
 
 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, users of :option:`-Weverything` therefore
+often disable many diagnostics such as :option:`-Wno-c++98-compat`
+:option:`-Wno-c++-compat`.
+
+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 once. 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), that
-flag wins.
+Note that when combined with :option:`-w` (which disables all warnings),
+disabling all warnings wins.
 
 Controlling Static Analyzer Diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 While not strictly part of the compiler, the diagnostics from Clang's
 `static analyzer <https://clang-analyzer.llvm.org>`_ can also be
 influenced by the user via changes to the source code. See the available
 `annotations <https://clang-analyzer.llvm.org/annotations.html>`_ and the