docs: added a general note about macro usage
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 452f627..da99dac 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -318,14 +318,7 @@
>>> call_go(c)
u'meow! meow! meow! '
-.. warning::
-
- The :func:`PYBIND11_OVERLOAD_*` calls are all just macros, which means that
- they can get confused by commas in a template argument such as
- ``PYBIND11_OVERLOAD(MyReturnValue<T1, T2>, myFunc)``. In this case, the
- preprocessor assumes that the comma indicates the beginnning of the next
- parameter. Use a ``typedef`` to bind the template to another name and use
- it in the macro to avoid this problem.
+Please take a look at the :ref:`macro_notes` before using this feature.
.. seealso::
@@ -334,6 +327,21 @@
detail.
+.. _macro_notes:
+
+General notes regarding convenience macros
+==========================================
+
+pybind11 provides a few convenience macros such as
+:func:`PYBIND11_MAKE_OPAQUE` and :func:`PYBIND11_DECLARE_HOLDER_TYPE`, and
+``PYBIND11_OVERLOAD_*``. Since these are "just" macros that are evaluated
+in the preprocessor (which has no concept of types), they *will* get confused
+by commas in a template argument such as ``PYBIND11_OVERLOAD(MyReturnValue<T1,
+T2>, myFunc)``. In this case, the preprocessor assumes that the comma indicates
+the beginnning of the next parameter. Use a ``typedef`` to bind the template to
+another name and use it in the macro to avoid this problem.
+
+
Global Interpreter Lock (GIL)
=============================
@@ -721,6 +729,9 @@
class Child : public std::enable_shared_from_this<Child> { };
+
+Please take a look at the :ref:`macro_notes` before using this feature.
+
.. seealso::
The file :file:`example/example8.cpp` contains a complete example that
@@ -903,6 +914,7 @@
}, py::keep_alive<0, 1>()) /* Keep vector alive while iterator is used */
// ....
+Please take a look at the :ref:`macro_notes` before using this feature.
.. seealso::