[Clang][Comments] Attach comments to decl even if preproc directives are in between

clang/docs/ReleaseNotes.rst

@@ -152,6 +152,22 @@ Clang Frontend Potentially Breaking Changes
 - The ``hasTypeLoc`` AST matcher will no longer match a ``classTemplateSpecializationDecl``;
   existing uses should switch to ``templateArgumentLoc`` or ``hasAnyTemplateArgumentLoc`` instead.
 
+- The comment parser now matches comments to declarations even if there is a
+  preprocessor macro in between the comment and declaration. This change is
+  intended to improve Clang's support for parsing documentation comments and
+  to better conform to Doxygen's behavior.
+
+  This has the potential to cause ``-Wdocumentation`` warnings, especially in
+  cases where a function-like macro has a documentation comment and is followed
+  immediately by a normal function. The function-like macro's documentation
+  comments will be attributed to the subsequent function and may cause
+  ``-Wdocumentation`` warnings such as mismatched parameter names, or invalid
+  return documentation comments.
+
+  In cases where the ``-Wdocumentation`` warnings are thrown, the suggested fix
+  is to document the declaration following the macro so that the warnings are
+  fixed.
+
 Clang Python Bindings Potentially Breaking Changes
 --------------------------------------------------
 - Renamed ``CursorKind`` variant 272 from ``OMP_TEAMS_DISTRIBUTE_DIRECTIVE``

clang/lib/AST/ASTContext.cpp

@@ -284,9 +284,10 @@ RawComment *ASTContext::getRawCommentForDeclNoCacheImpl(
   StringRef Text(Buffer + CommentEndOffset,
                  DeclLocDecomp.second - CommentEndOffset);
 
-  // There should be no other declarations or preprocessor directives between
-  // comment and declaration.
-  if (Text.find_last_of(";{}#@") != StringRef::npos)
+  // There should be no other declarations between comment and declaration.
+  // Preprocessor directives are implicitly allowed to be between a comment and
+  // its associated decl.
+  if (Text.find_last_of(";{}@") != StringRef::npos)
     return nullptr;
 
   return CommentBeforeDecl;

clang/lib/Headers/amxcomplexintrin.h

@@ -107,6 +107,24 @@
 ///    The 2nd source tile. Max size is 1024 Bytes.
 #define _tile_cmmrlfp16ps(dst, a, b) __builtin_ia32_tcmmrlfp16ps(dst, a, b)
 
+/// Perform matrix multiplication of two tiles containing complex elements and
+///    accumulate the results into a packed single precision tile.
+///
+/// \param m
+///    The number of rows in the first tile and the number of rows in the result
+///    tile.
+/// \param n
+///    The number of columns in the second tile and the number of columns in the
+///    result tile.
+/// \param k
+///    The number of columns in the first tile and the number of rows in the
+///    second tile.
+/// \param dst
+///    Pointer to the destination tile where the result will be stored.
+/// \param src1
+///    Pointer to the first source tile.
+/// \param src2
+///    Pointer to the second source tile.
 static __inline__ _tile1024i __DEFAULT_FN_ATTRS_COMPLEX
 _tile_cmmimfp16ps_internal(unsigned short m, unsigned short n, unsigned short k,
                            _tile1024i dst, _tile1024i src1, _tile1024i src2) {

clang/lib/Headers/ia32intrin.h

@@ -533,6 +533,13 @@ __rdtscp(unsigned int *__A) {
 /// \see __rdpmc
 #define _rdpmc(A) __rdpmc(A)
 
+/// Invalidates the contents of the processor's internal caches.
+///    This function writes back and invalidates all modified cache lines in
+///    the processor.
+///
+/// \headerfile <x86intrin.h>
+///
+/// This intrinsic corresponds to the \c WBINVD instruction.
 static __inline__ void __DEFAULT_FN_ATTRS
 _wbinvd(void) {
   __builtin_ia32_wbinvd();

clang/test/Index/annotate-comments.cpp

@@ -204,9 +204,9 @@ void isdoxy45(void);
 /// Ggg. IS_DOXYGEN_END
 void isdoxy46(void);
 
-/// IS_DOXYGEN_NOT_ATTACHED
+/// isdoxy47 IS_DOXYGEN_SINGLE
 #define FOO
-void notdoxy47(void);
+void isdoxy47(void);
 
 /// IS_DOXYGEN_START Aaa bbb
 /// \param ccc
@@ -330,6 +330,7 @@ void isdoxy54(int);
 // CHECK: annotate-comments.cpp:185:6: FunctionDecl=isdoxy44:{{.*}} BriefComment=[IS_DOXYGEN_START Aaa bbb ccc.]
 // CHECK: annotate-comments.cpp:195:6: FunctionDecl=isdoxy45:{{.*}} BriefComment=[Ddd eee. Fff.]
 // CHECK: annotate-comments.cpp:205:6: FunctionDecl=isdoxy46:{{.*}} BriefComment=[Ddd eee. Fff.]
+// CHECK: annotate-comments.cpp:209:6: FunctionDecl=isdoxy47:{{.*}} isdoxy47 IS_DOXYGEN_SINGLE
 // CHECK: annotate-comments.cpp:214:6: FunctionDecl=isdoxy48:{{.*}} BriefComment=[IS_DOXYGEN_START Aaa bbb]
 // CHECK: annotate-comments.cpp:218:6: FunctionDecl=isdoxy49:{{.*}} BriefComment=[IS_DOXYGEN_START Aaa]
 // CHECK: annotate-comments.cpp:222:6: FunctionDecl=isdoxy50:{{.*}} BriefComment=[Returns ddd IS_DOXYGEN_END]