From 821023547864dfba0662965dd1f895edf08728f4 Mon Sep 17 00:00:00 2001
From: Nicolas Stucki <nicolas.stucki@gmail.com>
Date: Tue, 28 Feb 2023 14:32:56 +0100
Subject: [PATCH] Helpful implicit not found message for `Quotes`

Fixes #16888
---
 library/src/scala/quoted/Quotes.scala      | 19 +++++++++++++++++++
 tests/neg-custom-args/explain/i16888.check | 14 ++++++++++++++
 tests/neg-custom-args/explain/i16888.scala |  1 +
 tests/neg-macros/i6436.check               |  2 ++
 4 files changed, 36 insertions(+)
 create mode 100644 tests/neg-custom-args/explain/i16888.check
 create mode 100644 tests/neg-custom-args/explain/i16888.scala

diff --git a/library/src/scala/quoted/Quotes.scala b/library/src/scala/quoted/Quotes.scala
index 22ec107aeae8..05c253a76fd3 100644
--- a/library/src/scala/quoted/Quotes.scala
+++ b/library/src/scala/quoted/Quotes.scala
@@ -1,6 +1,7 @@
 package scala.quoted
 
 import scala.annotation.experimental
+import scala.annotation.implicitNotFound
 import scala.reflect.TypeTest
 
 /** Current Quotes in scope
@@ -21,7 +22,25 @@ transparent inline def quotes(using q: Quotes): q.type = q
  *
  *  It contains the low-level Typed AST API metaprogramming API.
  *  This API does not have the static type guarantees that `Expr` and `Type` provide.
+ *  `Quotes` are generated from an enclosing `${ ... }` or `scala.staging.run`. For example:
+ *  ```scala sc:nocompile
+ *  import scala.quoted._
+ *  inline def myMacro: Expr[T] =
+ *    ${ /* (quotes: Quotes) ?=> */ myExpr }
+ *  def myExpr(using Quotes): Expr[T] =
+ *    '{ f(${ /* (quotes: Quotes) ?=> */ myOtherExpr }) }
+ *  }
+ *  def myOtherExpr(using Quotes): Expr[U] = '{ ... }
+ *  ```
  */
+
+@implicitNotFound("""explain=Maybe this methods is missing a `(using Quotes)` parameter.
+
+Maybe that splice `$ { ... }` is missing?
+Given instances of `Quotes` are generated from an enclosing splice `$ { ... }` (or `scala.staging.run` call).
+A splice can be thought as a method with the following signature.
+  def $[T](body: Quotes ?=> Expr[T]): T
+""")
 trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
 
   // Extension methods for `Expr[T]`
diff --git a/tests/neg-custom-args/explain/i16888.check b/tests/neg-custom-args/explain/i16888.check
new file mode 100644
index 000000000000..e184ea418a94
--- /dev/null
+++ b/tests/neg-custom-args/explain/i16888.check
@@ -0,0 +1,14 @@
+-- [E172] Type Error: tests/neg-custom-args/explain/i16888.scala:1:38 --------------------------------------------------
+1 |def test = summon[scala.quoted.Quotes] // error
+  |                                      ^
+  |               No given instance of type quoted.Quotes was found for parameter x of method summon in object Predef
+  |---------------------------------------------------------------------------------------------------------------------
+  | Explanation (enabled by `-explain`)
+  |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  | Maybe this methods is missing a `(using Quotes)` parameter.
+  |
+  | Maybe that splice `$ { ... }` is missing?
+  | Given instances of `Quotes` are generated from an enclosing splice `$ { ... }` (or `scala.staging.run` call).
+  | A splice can be thought as a method with the following signature.
+  |   def $[T](body: Quotes ?=> Expr[T]): T
+   ---------------------------------------------------------------------------------------------------------------------
diff --git a/tests/neg-custom-args/explain/i16888.scala b/tests/neg-custom-args/explain/i16888.scala
new file mode 100644
index 000000000000..9d3fd0f2f57e
--- /dev/null
+++ b/tests/neg-custom-args/explain/i16888.scala
@@ -0,0 +1 @@
+def test = summon[scala.quoted.Quotes] // error
diff --git a/tests/neg-macros/i6436.check b/tests/neg-macros/i6436.check
index 43e93b2e64e5..d563abb5424c 100644
--- a/tests/neg-macros/i6436.check
+++ b/tests/neg-macros/i6436.check
@@ -2,6 +2,8 @@
 5 |    case '{ StringContext(${Varargs(parts)}*) } => // error
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |         No given instance of type scala.quoted.Quotes was found
+  |
+  | longer explanation available when compiling with `-explain`
 -- [E006] Not Found Error: tests/neg-macros/i6436.scala:6:34 -----------------------------------------------------------
 6 |      val ps: Seq[Expr[String]] = parts // error
   |                                  ^^^^^