[libcxx-commits] [libcxx] [libcxx][docs] Make test name pattern documentation more obvious (PR #73136)

[Louis Dionne via libcxx-commits]

================
@@ -325,18 +325,98 @@ This macro is in a different header as ``assert_macros.h`` since it pulls in
 additional headers.
 
  .. note: This macro can only be used in test using C++20 or newer. The macro
-          was added at a time where most of lib++'s C++17 support was complete.
+          was added at a time where most of libc++'s C++17 support was complete.
           Since it is not expected to add this to existing tests no effort was
           taken to make it work in earlier language versions.
 
 
-Additional reading
-------------------
-
-The function ``CxxStandardLibraryTest`` in the file
-``libcxx/utils/libcxx/test/format.py`` has documentation about writing test. It
-explains the difference between the test named  ``foo.pass.cpp`` and named
-``foo.verify.cpp`` are.
+Test names
+----------
+
+The names of test files have meaning for the libc++-specific configuration of
+Lit. Based on the pattern that matches the name of a test file, Lit will test
+the code contained therein in different ways. Refer to the `Lit Meaning of libc++
+Test Filenames`_ when determining the names for new test files.
+
+.. _Lit Meaning of libc++ Test Filenames:
+.. list-table:: Lit Meaning of libc++ Test Filenames
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Name Pattern
+     - Meaning
+   * - ``FOO.pass.cpp``
+     - Checks whether the C++ code in the file compiles, links and runs successfully.
+   * - ``FOO.pass.mm``
+     - Same as ``FOO.pass.cpp``, but for Objective-C++.
+
+   * - ``FOO.compile.pass.cpp``
+     - Checks whether the C++ code in the file compiles successfully. In general, prefer `compile` tests over `verify` tests, 
----------------
ldionne wrote:

I think it's valid RST code, it will just render weird.

https://github.com/llvm/llvm-project/pull/73136