[ASTMatchers] Add an isMain() matcher

[aaron.ballman]

LGTM, though if you can split the unrelated changes out into a separate commit, that would be great.

clang/docs/LibASTMatchersReference.html

3284 ↗

(On Diff #156599)

It seems like there are a lot of unrelated changes in the patch. If you could submit these separately, that'd be great -- it doesn't require review.

[george.karpenkov]

clang/docs/LibASTMatchersReference.html

3284 ↗

(On Diff #156599)

that's because there's no mechanism enforcing HTML generation before the commit.
Why do we even have HTML in the repo? Couldn't that just be generated by the website on post-receive hook?

[aaron.ballman]

clang/docs/LibASTMatchersReference.html

3284 ↗

(On Diff #156599)

Auto-generated documentation is a newer concept; I suspect we could do it here as well and stop committing the HTML, but no one's worked on such functionality. Personally, I'd be happy to see that functionality added if it doesn't cause problems on the server side of things. If you're interested in working on something like that, I'd recommend starting a thread on cfe-dev and be sure to include @tonic as she did the infrastructure for attribute and command line documentation generation.

[george.karpenkov]

@aaron.ballman Right, I see. I don't have resources to work on that though.

My bigger point was that under the current setup it's extremely easy to forget to update the HTML comments,
and many (if not most) of the commits do that.
Then it's completely unreasonable to put the burden of separating HTML changes into separate reviews
on a person who actually does do the right thing and runs the documentation generator.
If we don't have facilities for proper automatic documentation generation then we should just treat diffs on those as ignorable noise.

[aaron.ballman]

In D49615#1172043, @george.karpenkov wrote:

@aaron.ballman Right, I see. I don't have resources to work on that though.

My bigger point was that under the current setup it's extremely easy to forget to update the HTML comments,
and many (if not most) of the commits do that.
Then it's completely unreasonable to put the burden of separating HTML changes into separate reviews
on a person who actually does do the right thing and runs the documentation generator.
If we don't have facilities for proper automatic documentation generation then we should just treat diffs on those as ignorable noise.

I understand that perspective and somewhat agree with it. However, we don't typically allow "drive-by" fixes in other areas to come in as part of a commit, either. It makes code archaeology harder when there are unrelated parts of a commit that you have to research long after the commit happens.

This issue should be solved by making it an impossible situation, but until someone puts in that effort, the burden should remain on patch authors to generate the documentation and reviewers should continue to insist on the documentation being generated prior to committing any changes. This particular set of problems seems to have stemmed from r337209 because the HTML generated and committed with that commit was stale compared to what was in ASTMatchers.h. It seems we both messed that one up (it was your commit and my LG).

[george.karpenkov]

@aaron.ballman

It seems we both messed that one up

Not only though: there's also the typo fixed in hasUnqualifiedDesugaredType.

OK I'll separate this one.

[aaron.ballman]

In D49615#1172077, @george.karpenkov wrote:

@aaron.ballman

It seems we both messed that one up

Not only though: there's also the typo fixed in hasUnqualifiedDesugaredType.

Hah, good catch!

OK I'll separate this one.

Thank you.

docs/LibASTMatchersReference.html

Given
   namespace n {
   inline namespace m {}
   }
 functionDecl(isInline()) will match ::f().
 namespaceDecl(isInline()) will match n::m.
 </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('isMain0')"><a name="isMain0Anchor">isMain</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isMain0"><pre>Determines whether the function is "main", which is the entry point
+into an executable program.
+</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('isNoReturn0')"><a name="isNoReturn0Anchor">isNoReturn</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isNoReturn0"><pre>Matches FunctionDecls that have a noreturn attribute.
 
 Given
   void nope();
   [[noreturn]] void a();
   __attribute__((noreturn)) void b();
   struct c { [[noreturn]] c(); };

include/clang/ASTMatchers/ASTMatchers.h

 ///   matches 'int a;' and 'int b;' but not 'int c;'.
 AST_MATCHER_P(FieldDecl, hasInClassInitializer, internal::Matcher<Expr>,
               InnerMatcher) {
   const Expr *Initializer = Node.getInClassInitializer();
   return (Initializer != nullptr &&
           InnerMatcher.matches(*Initializer, Finder, Builder));
 }
 
+/// Determines whether the function is "main", which is the entry point
+/// into an executable program.
+AST_MATCHER(FunctionDecl, isMain) {
+  return Node.isMain();
+}
+
 /// Matches the specialized template of a specialization declaration.
 ///
 /// Given
 /// \code
 ///   tempalate<typename T> class A {};
 ///   typedef A<int> B;
 /// \endcode
 /// classTemplateSpecializationDecl(hasSpecializedTemplate(classTemplateDecl()))

lib/ASTMatchers/Dynamic/Registry.cpp

RegistryMaps::RegistryMaps() {
   REGISTER_MATCHER(isInstanceMessage);
   REGISTER_MATCHER(isInstantiated);
   REGISTER_MATCHER(isExpansionInSystemHeader);
   REGISTER_MATCHER(isInteger);
   REGISTER_MATCHER(isIntegral);
   REGISTER_MATCHER(isInTemplateInstantiation);
   REGISTER_MATCHER(isLambda);
   REGISTER_MATCHER(isListInitialization);
+  REGISTER_MATCHER(isMain);
   REGISTER_MATCHER(isMemberInitializer);
   REGISTER_MATCHER(isMoveAssignmentOperator);
   REGISTER_MATCHER(isMoveConstructor);
   REGISTER_MATCHER(isNoReturn);
   REGISTER_MATCHER(isNoThrow);
   REGISTER_MATCHER(isOverride);
   REGISTER_MATCHER(isPrivate);
   REGISTER_MATCHER(isProtected);

unittests/ASTMatchers/ASTMatchersNarrowingTest.cpp

TEST(IsAssignmentOperator, Basic) {
   EXPECT_TRUE(matches("void x() { int a; a &= 3; }", BinAsgmtOperator));
   EXPECT_TRUE(matches("struct S { S& operator=(const S&); };"
                       "void x() { S s1, s2; s1 = s2; }",
                       CXXAsgmtOperator));
   EXPECT_TRUE(
       notMatches("void x() { int a; if(a == 0) return; }", BinAsgmtOperator));
 }
 
+TEST(Matcher, isMain) {
+  EXPECT_TRUE(
+    matches("int main() {}", functionDecl(isMain())));
+
+  EXPECT_TRUE(
+    notMatches("int main2() {}", functionDecl(isMain())));
+}
+
 } // namespace ast_matchers
 } // namespace clang