1 files changed, 14 insertions, 1 deletions
diff --git a/ext/pybind11/tests/pybind11_tests.cpp b/ext/pybind11/tests/pybind11_tests.cpp
index 9c593eee1..1d805d75b 100644
--- a/ext/pybind11/tests/pybind11_tests.cpp
+++ b/ext/pybind11/tests/pybind11_tests.cpp
@@ -10,6 +10,19 @@
 #include "pybind11_tests.h"
 #include "constructor_stats.h"
 
+/*
+For testing purposes, we define a static global variable here in a function that each individual
+test .cpp calls with its initialization lambda.  It's convenient here because we can just not
+compile some test files to disable/ignore some of the test code.
+
+It is NOT recommended as a way to use pybind11 in practice, however: the initialization order will
+be essentially random, which is okay for our test scripts (there are no dependencies between the
+individual pybind11 test .cpp files), but most likely not what you want when using pybind11
+productively.
+
+Instead, see the "How can I reduce the build time?" question in the "Frequently asked questions"
+section of the documentation for good practice on splitting binding code over multiple files.
+*/
 std::list<std::function<void(py::module &)>> &initializers() {
     static std::list<std::function<void(py::module &)>> inits;
     return inits;
@@ -32,7 +45,7 @@ void bind_ConstructorStats(py::module &m) {
 }
 
 PYBIND11_PLUGIN(pybind11_tests) {
-    py::module m("pybind11_tests", "pybind example plugin");
+    py::module m("pybind11_tests", "pybind testing plugin");
 
     bind_ConstructorStats(m);