Merge 23a884d0b7981fbac47b84b969aa29c54937b152 into d72f9c8aea6817cdf1ca0ac10887f328de7f3da2

docs/faq.md

@@ -1,6 +1,6 @@
 # GoogleTest FAQ
 
-## Why should test suite names and test names not contain underscore?
+## Why are there restrictions on underscores in test suite and test names?
 
 {: .callout .note}
 Note: GoogleTest reserves underscore (`_`) for special-purpose keywords, such as
@@ -48,15 +48,25 @@ TEST(Time_Flies, Like_An_Arrow) { ... }
 Now, the two `TEST`s will both generate the same class
 (`Time_Flies_Like_An_Arrow_Test`). That's not good.
 
-So for simplicity, we just ask the users to avoid `_` in `TestSuiteName` and
-`TestName`. The rule is more constraining than necessary, but it's simple and
-easy to remember. It also gives GoogleTest some wiggle room in case its
-implementation needs to change in the future.
+GoogleTest allows underscores (`_`) in test suite names and test names.
+
+However, certain underscore patterns are prohibited by the C++ standard:
+
+1.  Any identifier that starts with an underscore followed by an upper-case
+    letter.
+2.  Any identifier that contains two consecutive underscores (`__`) anywhere in
+    its name.
+
+In addition, some combinations of underscores may cause internal name collisions
+in the generated test class names.
+
+
+If you violate the C++ reserved identifier rules or create a name collision,
+there may not be immediate consequences, but your test may break with a new
+compiler or a new version of GoogleTest. Therefore it is best to avoid leading
+or trailing underscores and avoid double underscores in test suite and test
+names.
 
-If you violate the rule, there may not be immediate consequences, but your test
-may (just may) break with a new compiler (or a new version of the compiler you
-are using) or with a new version of GoogleTest. Therefore it's best to follow
-the rule.
 
 ## Why does GoogleTest support `EXPECT_EQ(NULL, ptr)` and `ASSERT_EQ(NULL, ptr)` but not `EXPECT_NE(NULL, ptr)` and `ASSERT_NE(NULL, ptr)`?
 

docs/primer.md

@@ -162,10 +162,17 @@ TEST(TestSuiteName, TestName) {
 
 `TEST()` arguments go from general to specific. The *first* argument is the name
 of the test suite, and the *second* argument is the test's name within the test
-suite. Both names must be valid C++ identifiers, and they should not contain any
-underscores (`_`). A test's *full name* consists of its containing test suite
-and its individual name. Tests from different test suites can have the same
-individual name.
+suite. Both names must be valid C++ identifiers.
+
+Underscores (`_`) are allowed, but certain patterns are prohibited by the C++
+standard, including identifiers that begin with an underscore followed by an
+upper-case letter or that contain consecutive underscores (`__`). In addition,
+some underscore combinations may cause internal name collisions in generated
+test class names.
+
+A test's *full name* consists of its containing test suite and its individual
+name. Tests from different test suites can have the same individual name.
+
 
 For example, let's take a simple integer function:
 

docs/reference/testing.md

@@ -20,9 +20,17 @@ TEST(<em>TestSuiteName</em>, <em>TestName</em>) {
 Defines an individual test named *`TestName`* in the test suite
 *`TestSuiteName`*, consisting of the given statements.
 
-Both arguments *`TestSuiteName`* and *`TestName`* must be valid C++ identifiers
-and must not contain underscores (`_`). Tests in different test suites can have
-the same individual name.
+Both arguments *`TestSuiteName`* and *`TestName`* must be valid C++ identifiers.
+
+Underscores (`_`) are allowed, but identifiers must not:
+
+- start with an underscore followed by an upper-case letter, or
+- contain two consecutive underscores (`__`).
+
+These restrictions follow the C++ standard rules for reserved identifiers.
+
+Tests in different test suites can have the same individual name.
+
 
 The statements within the test body can be any code under test.
 [Assertions](assertions.md) used within the test body determine the outcome of
@@ -40,8 +48,17 @@ Defines an individual test named *`TestName`* that uses the test fixture class
 *`TestFixtureName`*. The test suite name is *`TestFixtureName`*.
 
 Both arguments *`TestFixtureName`* and *`TestName`* must be valid C++
-identifiers and must not contain underscores (`_`). *`TestFixtureName`* must be
-the name of a test fixture class—see
+identifiers.
+
+Underscores (`_`) are allowed, but identifiers must not:
+
+- start with an underscore followed by an upper-case letter, or
+- contain two consecutive underscores (`__`).
+
+These restrictions follow the C++ standard rules for reserved identifiers.
+
+*`TestFixtureName`* must be the name of a test fixture class—see
+
 [Test Fixtures](../primer.md#same-data-multiple-tests).
 
 The statements within the test body can be any code under test.
@@ -61,8 +78,17 @@ test fixture class *`TestFixtureName`*. The test suite name is
 *`TestFixtureName`*.
 
 Both arguments *`TestFixtureName`* and *`TestName`* must be valid C++
-identifiers and must not contain underscores (`_`). *`TestFixtureName`* must be
-the name of a value-parameterized test fixture class—see
+identifiers.
+
+Underscores (`_`) are allowed, but identifiers must not:
+
+- start with an underscore followed by an upper-case letter, or
+- contain two consecutive underscores (`__`).
+
+These restrictions follow the C++ standard rules for reserved identifiers.
+
+*`TestFixtureName`* must be the name of a value-parameterized test fixture class—see
+
 [Value-Parameterized Tests](../advanced.md#value-parameterized-tests).
 
 The statements within the test body can be any code under test. Within the test