Clarify comments about doc comments in macros.

Author: nnethercote

compiler/rustc_expand/src/mbe/macro_parser.rs

@@ -517,7 +517,12 @@ impl<'tt> TtParser<'tt> {
 
                     TokenTree::Token(t) => {
                         // If it's a doc comment, we just ignore it and move on to the next tt in
-                        // the matcher. If the token matches, we can just advance the parser.
+                        // the matcher. This is a bug, but #95267 showed that existing programs
+                        // rely on this behaviour, and changing it would require some care and a
+                        // transition period.
+                        //
+                        // If the token matches, we can just advance the parser.
+                        //
                         // Otherwise, this match has failed, there is nothing to do, and hopefully
                         // another item in `cur_items` will match.
                         if matches!(t, Token { kind: DocComment(..), .. }) {

src/test/ui/macros/issue-95267.rs

@@ -1,7 +1,8 @@
 // check-pass
 
-// This is a valid macro. Commit 4 in #95159 broke things such that it failed
-// with a "missing tokens in macro arguments" error, as reported in #95267.
+// The doc comment here is ignored. This is a bug, but #95267 showed that
+// existing programs rely on this behaviour, and changing it would require some
+// care and a transition period.
 macro_rules! f {
     (
         /// ab