From 239ae6d56ae545534cf69dc1c91000c620a5f8f7 Mon Sep 17 00:00:00 2001
From: "Jason R. Coombs" <jaraco@jaraco.com>
Date: Mon, 18 Oct 2021 13:54:29 -0400
Subject: [PATCH] Provide references to relevant docs and protocol definition
 for ease-of-use.

---
 docs/using.rst                 | 4 +++-
 importlib_resources/_legacy.py | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/using.rst b/docs/using.rst
index ec7f0fad..548fa58e 100644
--- a/docs/using.rst
+++ b/docs/using.rst
@@ -175,7 +175,9 @@ To port to the ``files()`` API, refer to the
 `_legacy module <https://github.com/python/importlib_resources/blob/66ea2dc7eb12b1be2322b7ad002cefb12d364dff/importlib_resources/_legacy.py>`_
 to see simple wrappers that enable drop-in replacement based on the
 preferred API, and either copy those or adapt the usage to utilize the
-``files`` and ``Traversable`` interfaces directly.
+``files`` and
+`Traversable <https://github.com/python/importlib_resources/blob/b665a3ea907d93b1b6457217f34e1bfc06f51fe6/importlib_resources/abc.py#L49-L114>`_
+interfaces directly.
 
 
 Extending
diff --git a/importlib_resources/_legacy.py b/importlib_resources/_legacy.py
index 7526d512..477f89e4 100644
--- a/importlib_resources/_legacy.py
+++ b/importlib_resources/_legacy.py
@@ -16,7 +16,9 @@ def deprecated(func):
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
         warnings.warn(
-            f"{func.__name__} is deprecated. Use files() instead.",
+            f"{func.__name__} is deprecated. Use files() instead. "
+            "Refer to https://importlib-resources.readthedocs.io"
+            "/en/latest/using.html#migrating-from-legacy for migration advice.",
             DeprecationWarning,
             stacklevel=2,
         )