diff --git a/docs/advanced.rst b/docs/advanced.rst
index 6f02c714e..e076dcd4a 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -393,7 +393,7 @@ information, it is not clear whether Python should take charge of the returned
 value and eventually free its resources, or if this is handled on the C++ side.
 For this reason, pybind11 provides a several `return value policy` annotations
 that can be passed to the :func:`module::def` and :func:`class_::def`
-functions. The default policy is :enum:`return_value_policy::automatic``.
+functions. The default policy is :enum:`return_value_policy::automatic`.
 
 
 +--------------------------------------------------+---------------------------------------------------------------------------+
@@ -504,6 +504,14 @@ be declared at the top level before any binding code:
 
     PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>);
 
+.. warning::
+
+    The first argument of :func:`PYBIND11_DECLARE_HOLDER_TYPE` should be a
+    placeholder name that is used as a template parameter of the second
+    argument. Thus, feel free to use any identifier, but use it consistently on
+    both sides; also, don't use the name of a type that already exists in your
+    codebase.
+
 .. seealso::
 
     The file :file:`example/example8.cpp` contains a complete example that