Add warning about binding multiple modules (#635)

Issue #633 suggests people might be tempted to copy the test scripts
self-binding code, but that's a bad idea for pretty much anything other
than a test suite with self-contained test code.

This commit adds a comment as such with a reference to the
documentation that tells people how to do it instead.

tests/pybind11_tests.cpp

@@ -10,6 +10,19 @@
 #include "pybind11_tests.h"
 #include "pybind11_tests.h"
 #include "constructor_stats.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() {
 std::list<std::function<void(py::module &)>> &initializers() {
     static std::list<std::function<void(py::module &)>> inits;
     static std::list<std::function<void(py::module &)>> inits;
     return inits;
     return inits;