[ClangFormat] Future-proof Standard option, allow floating or pinning to arbitrary lang version

Summary:
The historical context:
- clang-format was written when C++11 was current,
  and the main language-version concern was >> vs > > template-closers.
  An option was added to allow selection of the 03/11 behavior, or auto-detection.
- there was no option to choose simply "latest standard" so anyone who didn't
  ever want 03 behavior or auto-detection specified Cpp11.
- In r185149 this option started to affect lexer mode.
- no options were added to cover c++14, as parsing/formatting
  didn't change that much. The usage of Cpp11 to mean "latest" became
  codified e.g. in r206263
- c++17 added some new constructs. These were mostly backwards-compatible and so
  not used in old programs, so having no way to turn them off was OK.
- c++20 added some new constructs and keywords (e.g. co_*) that changed the
  meaning of existing programs, and people started to complain that
  the c++20 parsing couldn't be turned off.

New plan:
 - Default ('Auto') behavior remains unchanged: parse as latest, format
   template-closers based on input.
 - Add new 'Latest' option that more clearly expresses the intent "use
   modern features" that many projects have chosen for their .clang-format files.
 - Allow pinning to *any* language version, using the same name as clang -std:
   c++03, c++11, c++14 etc. These set precise lexer options, and any
   clang-format code depending on these can use a >= check.
 - For backwards compatibility, `Cpp11` is an alias for `Latest`, not `c++11`.
   This matches the historical documented semantics of this option.
   This spelling (and `Cpp03`) are deprecated.

Reviewers: klimek, modocache

Subscribers: cfe-commits

Tags: #clang

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

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@373439 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 22 insertions, 6 deletions

diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst
index bd50943dfd..0803e65df2 100644
--- a/docs/ClangFormatStyleOptions.rst
+++ b/docs/ClangFormatStyleOptions.rst
@@ -2288,22 +2288,38 @@ the configuration (without a prefix: ``Auto``).
      std::unique_ptr<int[]> foo() {} // Won't be affected
 
 **Standard** (``LanguageStandard``)
-  Format compatible with this standard, e.g. use ``A<A<int> >``
-  instead of ``A<A<int>>`` for ``LS_Cpp03``.
+  .. code-block:: c++
+
+     c++03:                                 latest:
+     vector<set<int> > x;           vs.     vector<set<int>> x;
+  Parse and format C++ constructs compatible with this standard.
 
   Possible values:
 
-  * ``LS_Cpp03`` (in configuration: ``Cpp03``)
+  * ``LS_Cpp03`` (in configuration: ``c++03``)
     Use C++03-compatible syntax.
 
-  * ``LS_Cpp11`` (in configuration: ``Cpp11``)
-    Use features of C++11, C++14 and C++1z (e.g. ``A<A<int>>`` instead of
-    ``A<A<int> >``).
+  * ``LS_Cpp11`` (in configuration: ``c++11``)
+    Use C++11-compatible syntax.
+
+  * ``LS_Cpp14`` (in configuration: ``c++14``)
+    Use C++14-compatible syntax.
+
+  * ``LS_Cpp17`` (in configuration: ``c++17``)
+    Use C++17-compatible syntax.
+
+  * ``LS_Cpp20`` (in configuration: ``c++20``)
+    Use C++20-compatible syntax.
+
+  * ``LS_Latest`` (in configuration: ``Latest``)
+    Parse and format using the latest supported language version.
 
   * ``LS_Auto`` (in configuration: ``Auto``)
     Automatic detection based on the input.
 
+  * ``Cpp03``: deprecated alias for ``c++03``
 
+  * ``Cpp11``: deprecated alias for ``Latest``
 
 **StatementMacros** (``std::vector<std::string>``)
   A vector of macros that should be interpreted as complete