[common.h] Mark entry point as "unused".

This change defines a new, portable macro PYBIND11_MAYBE_UNUSED to
mark declarations as unused, and annotates the PYBIND11_MODULE entry
point with this attribute.

The purpose of this annotation is to facilitate dead code detection,
which might otherwise consider the module entry point function dead,
since it isn't otherwise used. (It is only used via FFI.)

Author: tkoeppe

include/pybind11/detail/common.h

@@ -92,6 +92,14 @@
 #  define PYBIND11_DEPRECATED(reason) __attribute__((deprecated(reason)))
 #endif
 
+#if defined(PYBIND11_CPP17)
+#  define PYBIND11_MAYBE_UNUSED [[maybe_unused]]
+#elif defined(_MSC_VER) && !defined(__clang__)
+#  define PYBIND11_MAYBE_UNUSED
+#else
+#  define PYBIND11_MAYBE_UNUSED __attribute__ ((__unused__))
+#endif
+
 #define PYBIND11_VERSION_MAJOR 2
 #define PYBIND11_VERSION_MINOR 5
 #define PYBIND11_VERSION_PATCH dev1
@@ -285,6 +293,10 @@ extern "C" {
     should not be in quotes. The second macro argument defines a variable of type
     `py::module` which can be used to initialize the module.
 
+    The entry point is marked as "maybe unused" to aid dead-code detection analysis:
+    since the entry point is typically only looked up at runtime and not referenced
+    during translation, it would otherwise appear as unused ("dead") code.
+
     .. code-block:: cpp
 
         PYBIND11_MODULE(example, m) {
@@ -297,6 +309,7 @@ extern "C" {
         }
 \endrst */
 #define PYBIND11_MODULE(name, variable)                                        \
+    PYBIND11_MAYBE_UNUSED                                                      \
     static void PYBIND11_CONCAT(pybind11_init_, name)(pybind11::module &);     \
     PYBIND11_PLUGIN_IMPL(name) {                                               \
         PYBIND11_CHECK_PYTHON_VERSION                                          \