Update MacroAnnotation documentation

Author: nicolasstucki

library/src/scala/annotation/MacroAnnotation.scala

@@ -14,11 +14,21 @@ trait MacroAnnotation extends StaticAnnotation:
    *  It returns a non-empty list containing the modified version of the annotated definition.
    *  The new tree for the definition must use the original symbol.
    *  New definitions can be added to the list before or after the transformed definitions, this order
-   *  will be retained.
-   *
-   *  All definitions in the result must have the same owner. The owner can be recovered from `tree.symbol.owner`.
-   *
-   *  The result cannot add new `class`, `object` or `type` definition. This limitation will be relaxed in the future.
+   *  will be retained. New definitions will not be visible from outside the macro expansion.
+   *
+   *  Restrictions:
+   *   - All definitions in the result must have the same owner. The owner can be recovered from `Symbol.spliceOwner`.
+   *     - Special case: an annotated top-level `def`, `val`, `var`, `lazy val` can return a `class`/`object`
+definition that is owned by the package or package object.
+   *   - Can not return a `type`.
+   *   - Annotated top-level `class`/`object` can not return top-level `def`, `val`, `var`, `lazy val`.
+   *   - Can not see new definition in user written code.
+   *
+   *  Good practices:
+   *   - Make your new definitions private if you can.
+   *   - New definitions added as class members should use a fresh name (`Symbol.freshName`) to avoid collisions.
+   *   - New top-level definitions should use a fresh name (`Symbol.freshName`) that includes the name of the annotated
+   *     member as a prefix to avoid collisions definitions added in other files.
    *
    *  IMPORTANT: When developing and testing a macro annotation, you must enable `-Xcheck-macros` and `-Ycheck:all`.
    *
@@ -184,5 +194,7 @@ trait MacroAnnotation extends StaticAnnotation:
    *
    *  @param Quotes Implicit instance of Quotes used for tree reflection
    *  @param tree   Tree that will be transformed
+   *
+   *  @syntax markdown
    */
   def transform(using Quotes)(tree: quotes.reflect.Definition): List[quotes.reflect.Definition]