a few more documentation improvements
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 6f02c71..e076dcd 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -393,7 +393,7 @@
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 @@
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