[ASTMatcher] Clarify isStaticStorageClass and hasStaticStorageDuration documents.

[aaron.ballman]

LGTM, thank you for the clarifications!

include/clang/ASTMatchers/ASTMatchers.h

3395

Might as well correct "key word" to be "keyword" instead, as a drive-by fix.

[hokein]

Address review comments

docs/LibASTMatchersReference.html

Given:
   void i() throw(int);
   void j() noexcept(false);
 functionDecl(isNoThrow()) and functionProtoType(isNoThrow())
   match the declarations of g, and h, but not f, i or j.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>&gt;</td><td class="name" onclick="toggle('isStaticStorageClass0')"><a name="isStaticStorageClass0Anchor">isStaticStorageClass</a></td><td></td></tr>
-<tr><td colspan="4" class="doc" id="isStaticStorageClass0"><pre>Matches variablefunction declarations that have static storage class
-(with "static" key word) written in the source.
+<tr><td colspan="4" class="doc" id="isStaticStorageClass0"><pre>Matches variablefunction declarations that have "static" storage
+class specifier ("static" keyword) written in the source.
 
 Given:
   static void f() {}
   static int i = 0;
+  extern int j;
+  int k;
 functionDecl(isStaticStorageClass())
   matches the function declaration f.
 varDecl(isStaticStorageClass())
   matches the variable declaration i.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html">FunctionDecl</a>&gt;</td><td class="name" onclick="toggle('isTemplateInstantiation0')"><a name="isTemplateInstantiation0Anchor">isTemplateInstantiation</a></td><td></td></tr>
void f() {
   static int y;
 }
 int z;
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>&gt;</td><td class="name" onclick="toggle('hasStaticStorageDuration0')"><a name="hasStaticStorageDuration0Anchor">hasStaticStorageDuration</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasStaticStorageDuration0"><pre>Matches a variable declaration that has static storage duration.
+It includes the variable declared at namespace scope and those declared
+with "static" and "extern" storage class specifiers.
 
-Example matches y and a, but not x or z.
-(matcher = varDecl(hasStaticStorageDuration())
 void f() {
   int x;
   static int y;
   thread_local int z;
 }
 int a;
+static int b;
+extern int c;
+varDecl(hasStaticStorageDuration())
+  matches the function declaration y, a, b and c.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>&gt;</td><td class="name" onclick="toggle('hasThreadStorageDuration0')"><a name="hasThreadStorageDuration0Anchor">hasThreadStorageDuration</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="hasThreadStorageDuration0"><pre>Matches a variable declaration that has thread storage duration.
 
 Example matches z, but not x, z, or a.
 (matcher = varDecl(hasThreadStorageDuration())
Given:
   extern "C" { void g() {} }
   void h() {}
 functionDecl(isExternC())
   matches the declaration of f and g, but not the declaration h
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>&gt;</td><td class="name" onclick="toggle('isStaticStorageClass1')"><a name="isStaticStorageClass1Anchor">isStaticStorageClass</a></td><td></td></tr>
-<tr><td colspan="4" class="doc" id="isStaticStorageClass1"><pre>Matches variablefunction declarations that have static storage class
-(with "static" key word) written in the source.
+<tr><td colspan="4" class="doc" id="isStaticStorageClass1"><pre>Matches variablefunction declarations that have "static" storage
+class specifier ("static" keyword) written in the source.
 
 Given:
   static void f() {}
   static int i = 0;
+  extern int j;
+  int k;
 functionDecl(isStaticStorageClass())
   matches the function declaration f.
 varDecl(isStaticStorageClass())
   matches the variable declaration i.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>&gt;</td><td class="name" onclick="toggle('isTemplateInstantiation1')"><a name="isTemplateInstantiation1Anchor">isTemplateInstantiation</a></td><td></td></tr>

include/clang/ASTMatchers/ASTMatchers.h

 /// }
 /// int a;
 /// \endcode
 AST_MATCHER(VarDecl, hasAutomaticStorageDuration) {
   return Node.getStorageDuration() == SD_Automatic;
 }
 
 /// \brief Matches a variable declaration that has static storage duration.
+/// It includes the variable declared at namespace scope and those declared
+/// with "static" and "extern" storage class specifiers.
 ///
-/// Example matches y and a, but not x or z.
-/// (matcher = varDecl(hasStaticStorageDuration())
 /// \code
 /// void f() {
 ///   int x;
 ///   static int y;
 ///   thread_local int z;
 /// }
 /// int a;
+/// static int b;
+/// extern int c;
+/// varDecl(hasStaticStorageDuration())
+///   matches the function declaration y, a, b and c.
 /// \endcode
 AST_MATCHER(VarDecl, hasStaticStorageDuration) {
   return Node.getStorageDuration() == SD_Static;
 }
 
 /// \brief Matches a variable declaration that has thread storage duration.
 ///
 /// Example matches z, but not x, z, or a.

 /// \endcode
 /// functionDecl(isExternC())
 ///   matches the declaration of f and g, but not the declaration h
 AST_POLYMORPHIC_MATCHER(isExternC, AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                                    VarDecl)) {
   return Node.isExternC();
 }
 
-/// \brief Matches variable/function declarations that have static storage class
-/// (with "static" key word) written in the source.
+/// \brief Matches variable/function declarations that have "static" storage
+/// class specifier ("static" keyword) written in the source.
 ///
 /// Given:
 /// \code
 ///   static void f() {}
 ///   static int i = 0;
+///   extern int j;
+///   int k;
 /// \endcode
 /// functionDecl(isStaticStorageClass())
 ///   matches the function declaration f.
 /// varDecl(isStaticStorageClass())
 ///   matches the variable declaration i.
 AST_POLYMORPHIC_MATCHER(isStaticStorageClass,
                         AST_POLYMORPHIC_SUPPORTED_TYPES(FunctionDecl,
                                                         VarDecl)) {

unittests/ASTMatchers/ASTMatchersNarrowingTest.cpp

TEST(Matcher, VarDecl_Storage) {
   M = varDecl(hasName("X"), hasGlobalStorage());
   EXPECT_TRUE(notMatches("void f() { int X; }", M));
   EXPECT_TRUE(matches("int X;", M));
   EXPECT_TRUE(matches("void f() { static int X; }", M));
 }
 
 TEST(Matcher, VarDecl_StorageDuration) {
   std::string T =
-    "void f() { int x; static int y; } int a;";
+    "void f() { int x; static int y; } int a;static int b;extern int c;";
 
   EXPECT_TRUE(matches(T, varDecl(hasName("x"), hasAutomaticStorageDuration())));
   EXPECT_TRUE(
     notMatches(T, varDecl(hasName("y"), hasAutomaticStorageDuration())));
   EXPECT_TRUE(
     notMatches(T, varDecl(hasName("a"), hasAutomaticStorageDuration())));
 
   EXPECT_TRUE(matches(T, varDecl(hasName("y"), hasStaticStorageDuration())));
   EXPECT_TRUE(matches(T, varDecl(hasName("a"), hasStaticStorageDuration())));
+  EXPECT_TRUE(matches(T, varDecl(hasName("b"), hasStaticStorageDuration())));
+  EXPECT_TRUE(matches(T, varDecl(hasName("c"), hasStaticStorageDuration())));
   EXPECT_TRUE(notMatches(T, varDecl(hasName("x"), hasStaticStorageDuration())));
 
   // FIXME: It is really hard to test with thread_local itself because not all
   // targets support TLS, which causes this to be an error depending on what
   // platform the test is being run on. We do not have access to the TargetInfo
   // object to be able to test whether the platform supports TLS or not.
   EXPECT_TRUE(notMatches(T, varDecl(hasName("x"), hasThreadStorageDuration())));
   EXPECT_TRUE(notMatches(T, varDecl(hasName("y"), hasThreadStorageDuration())));
TEST(IsExternC, MatchesExternCVariableDeclarations) {
   EXPECT_TRUE(notMatches("int i;", varDecl(isExternC())));
 }
 
 TEST(IsStaticStorageClass, MatchesStaticDeclarations) {
   EXPECT_TRUE(
       matches("static void f() {}", functionDecl(isStaticStorageClass())));
   EXPECT_TRUE(matches("static int i = 1;", varDecl(isStaticStorageClass())));
   EXPECT_TRUE(notMatches("int i = 1;", varDecl(isStaticStorageClass())));
+  EXPECT_TRUE(notMatches("extern int i;", varDecl(isStaticStorageClass())));
   EXPECT_TRUE(notMatches("void f() {}", functionDecl(isStaticStorageClass())));
 }
 
 TEST(IsDefaulted, MatchesDefaultedFunctionDeclarations) {
   EXPECT_TRUE(notMatches("class A { ~A(); };",
                          functionDecl(hasName("~A"), isDefaulted())));
   EXPECT_TRUE(matches("class B { ~B() = default; };",
                       functionDecl(hasName("~B"), isDefaulted())));