[clang][doxygen] Fix -Wdocumentation warning for tag typedefs

[jkorous]

Summary

For tag typedefs like this one:

/*!
@class Foo
*/
typedef class { } Foo;

clang with -Wdocumentation gives:

warning: '@class' command should not be used in a comment attached to a non-struct declaration [-Wdocumentation]

while doxygen seems fine with it.

There's @typedef command in doxygen but from the description its semantics seem different.
http://www.doxygen.nl/manual/commands.html#cmdtypedef
@struct and @class seem appropriate.
http://www.doxygen.nl/manual/commands.html#cmdstruct

rdar://problem/58960486

[jkorous]

fix test

[jkorous]

Apparently it's related to:

commit a433e7141fb3f697e6430437ee73b19076603c1b
Author: Sam McCall <[e-mail]>
Date:   Wed Nov 13 21:30:31 2019 +0100

    [AST] Attach comment in `/** doc */ typedef struct A {} B` to B as well as A.

...adding clangd folks.

[sammccall]

Thanks for fixing this!

clang/lib/AST/CommentSema.cpp

942

nit: dyn_cast_or_null on the next line and delete this?

972

nit: TypedefDecl (caps) and below

[vsapsai]

clang/test/Sema/warn-documentation-tag-typedef.cpp

14

I'm thinking about also testing non-anonymous structs like

typedef struct Bar { } Bar;

But maybe it's not different enough or already tested.

Another idea which is out of scope of this change is to test name mismatch in case clang warns about it. Something like

/*! 
@struct Abc
*/
typedef struct { } Xyz;

[jkorous]

@vsapsai Sorry! I read your comment only after landing this.

[chrish_ericsson_atx]

I reported this issue back in November, as https://bugs.llvm.org/show_bug.cgi?id=44143. This change fixes the bug -- I'll mark it as such.

clang/include/clang/AST/CommentSema.h

public:
   /// pointer.
   bool isFunctionOrBlockPointerVarLikeDecl();
   bool isFunctionOrMethodVariadic();
   bool isObjCMethodDecl();
   bool isObjCPropertyDecl();
   bool isTemplateOrSpecialization();
   bool isRecordLikeDecl();
   bool isClassOrStructDecl();
+  /// \return \c true if the declaration that this comment is attached to
+  /// declares either struct, class or tag typedef.
+  bool isClassOrStructOrTagTypedefDecl();
   bool isUnionDecl();
   bool isObjCInterfaceDecl();
   bool isObjCProtocolDecl();
   bool isClassTemplateDecl();
   bool isFunctionTemplateDecl();
 
   ArrayRef<const ParmVarDecl *> getParamVars();
 

clang/lib/AST/CommentSema.cpp

 //===--- CommentSema.cpp - Doxygen comment semantic analysis --------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "clang/AST/CommentSema.h"
 #include "clang/AST/Attr.h"
 #include "clang/AST/CommentCommandTraits.h"
 #include "clang/AST/CommentDiagnostic.h"
 #include "clang/AST/Decl.h"
 #include "clang/AST/DeclTemplate.h"
+#include "clang/Basic/LLVM.h"
 #include "clang/Basic/SourceManager.h"
 #include "clang/Lex/Preprocessor.h"
 #include "llvm/ADT/SmallString.h"
 #include "llvm/ADT/StringSwitch.h"
 
 namespace clang {
 namespace comments {
 

 
 void Sema::checkContainerDeclVerbatimLine(const BlockCommandComment *Comment) {
   const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID());
   if (!Info->IsRecordLikeDeclarationCommand)
     return;
   unsigned DiagSelect;
   switch (Comment->getCommandID()) {
     case CommandTraits::KCI_class:
-      DiagSelect = (!isClassOrStructDecl() && !isClassTemplateDecl()) ? 1 : 0;
+      DiagSelect =
+          (!isClassOrStructOrTagTypedefDecl() && !isClassTemplateDecl()) ? 1
+                                                                         : 0;
       // Allow @class command on @interface declarations.
       // FIXME. Currently, \class and @class are indistinguishable. So,
       // \class is also allowed on an @interface declaration
       if (DiagSelect && Comment->getCommandMarker() && isObjCInterfaceDecl())
         DiagSelect = 0;
       break;
     case CommandTraits::KCI_interface:
       DiagSelect = !isObjCInterfaceDecl() ? 2 : 0;
       break;
     case CommandTraits::KCI_protocol:
       DiagSelect = !isObjCProtocolDecl() ? 3 : 0;
       break;
     case CommandTraits::KCI_struct:
-      DiagSelect = !isClassOrStructDecl() ? 4 : 0;
+      DiagSelect = !isClassOrStructOrTagTypedefDecl() ? 4 : 0;
       break;
     case CommandTraits::KCI_union:
       DiagSelect = !isUnionDecl() ? 5 : 0;
       break;
     default:
       DiagSelect = 0;
       break;
   }
if (!ThisDeclInfo)
     return false;
   if (!ThisDeclInfo->IsFilled)
     inspectThisDecl();
   if (const RecordDecl *RD =
         dyn_cast_or_null<RecordDecl>(ThisDeclInfo->CurrentDecl))
     return RD->isUnion();
   return false;
 }
+static bool isClassOrStructDeclImpl(const Decl *D) {
+  if (auto *record = dyn_cast_or_null<RecordDecl>(D))
+    return !record->isUnion();
+
+  return false;
+}
 
 bool Sema::isClassOrStructDecl() {
   if (!ThisDeclInfo)
     return false;
   if (!ThisDeclInfo->IsFilled)
     inspectThisDecl();
-  return ThisDeclInfo->CurrentDecl &&
-         isa<RecordDecl>(ThisDeclInfo->CurrentDecl) &&
-         !isUnionDecl();
+
+  if (!ThisDeclInfo->CurrentDecl)
+    return false;
+
+  return isClassOrStructDeclImpl(ThisDeclInfo->CurrentDecl);
+}
+
+bool Sema::isClassOrStructOrTagTypedefDecl() {
+  if (!ThisDeclInfo)
+    return false;
+  if (!ThisDeclInfo->IsFilled)
+    inspectThisDecl();
+
+  if (!ThisDeclInfo->CurrentDecl)
+    return false;
+
+  if (isClassOrStructDeclImpl(ThisDeclInfo->CurrentDecl))
+    return true;
+
+  if (auto *ThisTypedefDecl = dyn_cast<TypedefDecl>(ThisDeclInfo->CurrentDecl)) {
+    auto UnderlyingType = ThisTypedefDecl->getUnderlyingType();
+    if (auto ThisElaboratedType = dyn_cast<ElaboratedType>(UnderlyingType)) {
+      auto DesugaredType = ThisElaboratedType->desugar();
+      if (auto *DesugaredTypePtr = DesugaredType.getTypePtrOrNull()) {
+        if (auto *ThisRecordType = dyn_cast<RecordType>(DesugaredTypePtr)) {
+          return isClassOrStructDeclImpl(ThisRecordType->getAsRecordDecl());
+        }
+      }
+    }
+  }
+
+  return false;
 }
 
 bool Sema::isClassTemplateDecl() {
   if (!ThisDeclInfo)
     return false;
   if (!ThisDeclInfo->IsFilled)
     inspectThisDecl();
   return ThisDeclInfo->CurrentDecl &&

clang/test/Sema/warn-documentation-tag-typedef.cpp

+// RUN: %clang_cc1 -Wdocumentation -fsyntax-only %s 2>&1 | FileCheck -allow-empty %s
+
+/*!
+@class Foo
+*/
+typedef class { } Foo;
+// CHECK-NOT: warning:
+
+/*! 
+@struct Bar
+*/
+typedef struct { } Bar;
+// CHECK-NOT: warning: