Merge pull request #10335 from dotty-staging/update-language-macro-docs

Update scala.language.experimental.macro documentation

Author: bishabosha

library/src/scalaShadowing/language.scala

@@ -198,16 +198,20 @@ object language {
 
     import languageFeature.experimental._
 
-    /** Where enabled, macro definitions are allowed. Macro implementations and
-     *  macro applications are unaffected; they can be used anywhere.
+    /** Where enabled, Scala 2 macro definitions are allowed. Scala 2 macro implementations and
+     *  macro applications are unaffected; they can be used anywhere. A Scala 2 macro definition
+     *  must be accompanied by a Scala 3 macro definition with the same signature.
      *
-     *  '''Why introduce the feature?''' Macros promise to make the language more regular,
+     *  '''Why introduce the feature?''' Scala 2 macros promise to make the language more regular,
      *  replacing ad-hoc language constructs with a general powerful abstraction
      *  capability that can express them. Macros are also a more disciplined and
      *  powerful replacement for compiler plugins.
      *
      *  '''Why control it?''' For their very power, macros can lead to code that is hard
      *  to debug and understand.
+     *
+     *  This is not required by Scala 3 macros as `inline` controls the basic generative macros.
+     *  More add-hoc macros must contain the import of reflection in thier code, making this import redundant.
      */
     implicit lazy val macros: macros = languageFeature.experimental.macros