doc: Add note about casting from `None` to `T*` (#1760)
* doc: Add note about casting from `None` to `T*`
* doc: reword 'none-to-pointer' note message
* doc: mention opaque types in 'none-to-pointer' note message
diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index 4d28f06..3e1a3ff 100644
--- a/docs/advanced/functions.rst
+++ b/docs/advanced/functions.rst
@@ -467,6 +467,15 @@
The default behaviour when the tag is unspecified is to allow ``None``.
+.. note::
+
+ Even when ``.none(true)`` is specified for an argument, ``None`` will be converted to a
+ ``nullptr`` *only* for custom and :ref:`opaque <opaque>` types. Pointers to built-in types
+ (``double *``, ``int *``, ...) and STL types (``std::vector<T> *``, ...; if ``pybind11/stl.h``
+ is included) are copied when converted to C++ (see :doc:`/advanced/cast/overview`) and will
+ not allow ``None`` as argument. To pass optional argument of these copied types consider
+ using ``std::optional<T>``
+
Overload resolution order
=========================