Comment AST: Recognize function-like objects via return type (NFC)

[aaronpuchert]

Summary

Instead of pretending that function pointer type aliases or variables
are functions, and thereby losing the information that they are type
aliases or variables, respectively, we use the existence of a return
type in the DeclInfo to signify a "function-like" object.

That seems pretty natural, since it's also the return type (or parameter
list) from the DeclInfo that we compare the documentation with.

Addresses a concern voiced in D111264#3115104.

[gribozavr2]

Nice, thanks!

clang/include/clang/AST/Comment.h

enum DeclKind {
     /// Something that we consider a "function":
     /// \li function,
     /// \li function template,
     /// \li function template specialization,
     /// \li member function,
     /// \li member function template,
     /// \li member function template specialization,
     /// \li ObjC method,
-    /// \li variable of function pointer, member function pointer or block type,
-    /// \li a typedef for a function pointer, member function pointer,
-    ///     ObjC block.
     FunctionKind,
 
     /// Something that we consider a "class":
     /// \li class/struct,
     /// \li class template,
     /// \li class template (partial) specialization.
     ClassKind,
 
struct DeclInfo {
 
   DeclKind getKind() const LLVM_READONLY {
     return static_cast<DeclKind>(Kind);
   }
 
   TemplateDeclKind getTemplateKind() const LLVM_READONLY {
     return static_cast<TemplateDeclKind>(TemplateKind);
   }
+
+  bool involvesFunctionType() const { return !ReturnType.isNull(); }
 };
 
 /// A full comment attached to a declaration, contains block content.
 class FullComment : public Comment {
   ArrayRef<BlockContentComment *> Blocks;
   DeclInfo *ThisDeclInfo;
 
 public:

clang/include/clang/AST/CommentSema.h

public:
   void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
 
   void checkContainerDecl(const BlockCommandComment *Comment);
 
   /// Resolve parameter names to parameter indexes in function declaration.
   /// Emit diagnostics about unknown parametrs.
   void resolveParamCommandIndexes(const FullComment *FC);
 
+  /// \returns \c true if the declaration that this comment is attached to
+  /// is a pointer to function/method/block type or has such a type.
+  bool involvesFunctionType();
+
   bool isFunctionDecl();
   bool isAnyFunctionDecl();
 
   /// \returns \c true if declaration that this comment is attached to declares
   /// a function pointer.
   bool isFunctionPointerVarDecl();
   bool isFunctionOrMethodVariadic();
   bool isObjCMethodDecl();

clang/lib/AST/Comment.cpp

case Decl::CXXConversion: {
 
     if (K == Decl::CXXMethod || K == Decl::CXXConstructor ||
         K == Decl::CXXDestructor || K == Decl::CXXConversion) {
       const CXXMethodDecl *MD = cast<CXXMethodDecl>(CommentDecl);
       IsInstanceMethod = MD->isInstance();
       IsClassMethod = !IsInstanceMethod;
     }
     IsVariadic = FD->isVariadic();
+    assert(involvesFunctionType());
     break;
   }
   case Decl::ObjCMethod: {
     const ObjCMethodDecl *MD = cast<ObjCMethodDecl>(CommentDecl);
     Kind = FunctionKind;
     ParamVars = MD->parameters();
     ReturnType = MD->getReturnType();
     IsObjCMethod = true;
     IsInstanceMethod = MD->isInstanceMethod();
     IsClassMethod = !IsInstanceMethod;
     IsVariadic = MD->isVariadic();
+    assert(involvesFunctionType());
     break;
   }
   case Decl::FunctionTemplate: {
     const FunctionTemplateDecl *FTD = cast<FunctionTemplateDecl>(CommentDecl);
     Kind = FunctionKind;
     TemplateKind = Template;
     const FunctionDecl *FD = FTD->getTemplatedDecl();
     ParamVars = FD->parameters();
     ReturnType = FD->getReturnType();
     TemplateParameters = FTD->getTemplateParameters();
     IsVariadic = FD->isVariadic();
+    assert(involvesFunctionType());
     break;
   }
   case Decl::ClassTemplate: {
     const ClassTemplateDecl *CTD = cast<ClassTemplateDecl>(CommentDecl);
     Kind = ClassKind;
     TemplateKind = Template;
     TemplateParameters = CTD->getTemplateParameters();
     break;
void DeclInfo::fill() {
   }
 
   // If the type is a typedef / using to something we consider a function,
   // extract arguments and return type.
   if (TSI) {
     TypeLoc TL = TSI->getTypeLoc().getUnqualifiedLoc();
     FunctionTypeLoc FTL;
     if (getFunctionTypeLoc(TL, FTL)) {
-      Kind = FunctionKind;
       ParamVars = FTL.getParams();
       ReturnType = FTL.getReturnLoc().getType();
       if (const auto *FPT = dyn_cast<FunctionProtoType>(FTL.getTypePtr()))
         IsVariadic = FPT->isVariadic();
+      assert(involvesFunctionType());
     }
   }
 
   IsFilled = true;
 }
 
 StringRef ParamCommandComment::getParamName(const FullComment *FC) const {
   assert(isParamIndexValid());

clang/lib/AST/CommentSema.cpp

ParamCommandComment *Sema::actOnParamCommandStart(
                                       SourceLocation LocBegin,
                                       SourceLocation LocEnd,
                                       unsigned CommandID,
                                       CommandMarkerKind CommandMarker) {
   ParamCommandComment *Command =
       new (Allocator) ParamCommandComment(LocBegin, LocEnd, CommandID,
                                           CommandMarker);
 
-  if (!isFunctionDecl())
+  if (!involvesFunctionType())
     Diag(Command->getLocation(),
          diag::warn_doc_param_not_attached_to_a_function_decl)
       << CommandMarker
       << Command->getCommandNameRange(Traits);
 
   return Command;
 }
 
if (!Traits.getCommandInfo(Command->getCommandID())->IsReturnsCommand)
     return;
 
   assert(ThisDeclInfo && "should not call this check on a bare comment");
 
   // We allow the return command for all @properties because it can be used
   // to document the value that the property getter returns.
   if (isObjCPropertyDecl())
     return;
-  if (isFunctionDecl()) {
+  if (involvesFunctionType()) {
     assert(!ThisDeclInfo->ReturnType.isNull() &&
            "should have a valid return type");
     if (ThisDeclInfo->ReturnType->isVoidType()) {
       unsigned DiagKind;
       switch (ThisDeclInfo->CommentDecl->getKind()) {
       default:
         if (ThisDeclInfo->IsObjCMethod)
           DiagKind = 3;
if (const FunctionDecl *FD = dyn_cast<FunctionDecl>(D)) {
     TextToInsert += " ";
     SourceLocation Loc = FD->getSourceRange().getBegin();
     Diag(Loc, diag::note_add_deprecation_attr)
         << FixItHint::CreateInsertion(Loc, TextToInsert);
   }
 }
 
 void Sema::resolveParamCommandIndexes(const FullComment *FC) {
-  if (!isFunctionDecl()) {
+  if (!involvesFunctionType()) {
     // We already warned that \\param commands are not attached to a function
     // decl.
     return;
   }
 
   SmallVector<ParamCommandComment *, 8> UnresolvedParamCommands;
 
   // Comment AST nodes that correspond to \c ParamVars for which we have
if (CorrectedParamIndex != ParamCommandComment::InvalidParamIndex) {
       if (const IdentifierInfo *CorrectedII = CorrectedPVD->getIdentifier())
         Diag(ArgRange.getBegin(), diag::note_doc_param_name_suggestion)
           << CorrectedII->getName()
           << FixItHint::CreateReplacement(ArgRange, CorrectedII->getName());
     }
   }
 }
 
+bool Sema::involvesFunctionType() {
+  if (!ThisDeclInfo)
+    return false;
+  if (!ThisDeclInfo->IsFilled)
+    inspectThisDecl();
+  return ThisDeclInfo->involvesFunctionType();
+}
+
 bool Sema::isFunctionDecl() {
   if (!ThisDeclInfo)
     return false;
   if (!ThisDeclInfo->IsFilled)
     inspectThisDecl();
   return ThisDeclInfo->getKind() == DeclInfo::FunctionKind;
 }