deprecated py::base<>, added a macro for improved readability

docs/classes.rst

@@ -185,10 +185,9 @@ inheritance relationship:
         std::string bark() const { return "woof!"; }
     };
 
-There are three different ways of indicating a hierarchical relationship to
+There are two different ways of indicating a hierarchical relationship to
 pybind11: the first specifies the C++ base class as an extra template
-parameter of the :class:`class_`; the second uses a special ``base`` attribute
+parameter of the :class:`class_`:
-passed into the constructor:
 
 .. code-block:: cpp
 
@@ -201,11 +200,6 @@ passed into the constructor:
         .def(py::init<const std::string &>())
         .def("bark", &Dog::bark);
 
-    // Method 2: py::base attribute:
-    py::class_<Dog>(m, "Dog", py::base<Pet>() /* <- specify C++ parent type */)
-        .def(py::init<const std::string &>())
-        .def("bark", &Dog::bark);
-
 Alternatively, we can also assign a name to the previously bound ``Pet``
 :class:`class_` object and reference it when binding the ``Dog`` class:
 
@@ -215,13 +209,13 @@ Alternatively, we can also assign a name to the previously bound ``Pet``
     pet.def(py::init<const std::string &>())
        .def_readwrite("name", &Pet::name);
 
-    // Method 3: pass parent class_ object:
+    // Method 2: pass parent class_ object:
     py::class_<Dog>(m, "Dog", pet /* <- specify Python parent type */)
         .def(py::init<const std::string &>())
         .def("bark", &Dog::bark);
 
-Functionality-wise, all three approaches are completely equivalent. Afterwards,
+Functionality-wise, both approaches are equivalent. Afterwards, instances will
-instances will expose fields and methods of both types:
+expose fields and methods of both types:
 
 .. code-block:: pycon
 

include/pybind11/attr.h

@@ -33,7 +33,10 @@ struct name { const char *value; name(const char *value) : value(value) { } };
 struct sibling { handle value; sibling(const handle &value) : value(value.ptr()) { } };
 
 /// Annotation indicating that a class derives from another given type
-template <typename T> struct base { };
+template <typename T> struct base {
+    PYBIND11_DEPRECATED("base<T>() was deprecated in favor of specifying 'T' as a template argument to class_")
+    base() { }
+};
 
 /// Keep patient alive while nurse lives
 template <int Nurse, int Patient> struct keep_alive { };

include/pybind11/common.h

@@ -30,6 +30,16 @@
 #  define PYBIND11_NOINLINE __attribute__ ((noinline))
 #endif
 
+#if __cplusplus > 201103L
+#  define PYBIND11_DEPRECATED(reason) [[deprecated(reason)]]
+#elif defined(__clang__)
+#  define PYBIND11_DEPRECATED(reason) __attribute__((deprecated(reason)))
+#elif defined(__GNUG__)
+#  define PYBIND11_DEPRECATED(reason) __attribute__((deprecated))
+#elif defined(_MSC_VER)
+#  define PYBIND11_DEPRECATED(reason) __declspec(deprecated)
+#endif
+
 #define PYBIND11_VERSION_MAJOR 1
 #define PYBIND11_VERSION_MINOR 9
 #define PYBIND11_VERSION_PATCH dev0

include/pybind11/pytypes.h

@@ -43,10 +43,8 @@ public:
     bool is_none() const { return m_ptr == Py_None; }
     template <typename T> T cast() const;
     template <return_value_policy policy = return_value_policy::automatic_reference, typename ... Args>
-    #if __cplusplus > 201103L
+    PYBIND11_DEPRECATED("call(...) was deprecated in favor of operator()(...)")
-    [[deprecated("call(...) was deprecated in favor of operator()(...)")]]
+        object call(Args&&... args) const;
-    #endif
-    object call(Args&&... args) const;
     template <return_value_policy policy = return_value_policy::automatic_reference, typename ... Args>
     object operator()(Args&&... args) const;
     operator bool() const { return m_ptr != nullptr; }