Minor py::capsule cleanup. No functional change. (#4238)

Use `PyCapsule_Destructor` (part of the stable Python ABI) instead of spelling out the C `typedef`. The deprecation message is misleading. Replace with a message pointing to another existing ctor. Background: According to @wjakob the original motivation for deprecating the ctor (in PR #752) was to hide Python C API details, but PR #902 brought those back with a new ctor, it cannot be avoided. Having a `PyCapsule_Destructor` or a `void (*destructor)(void *)` are two separate and valid use cases.

Author: rwgk

include/pybind11/pytypes.h

@@ -1809,16 +1809,16 @@ class capsule : public object {
 
  explicit capsule(const void *value,
  const char *name = nullptr,
- void (*destructor)(PyObject *) = nullptr)
+ PyCapsule_Destructor destructor = nullptr)
  : object(PyCapsule_New(const_cast<void *>(value), name, destructor), stolen_t{}) {
  if (!m_ptr) {
  throw error_already_set();
  }
  }
 
- PYBIND11_DEPRECATED("Please pass a destructor that takes a void pointer as input")
- capsule(const void *value, void (*destruct)(PyObject *))
- : object(PyCapsule_New(const_cast<void *>(value), nullptr, destruct), stolen_t{}) {
+ PYBIND11_DEPRECATED("Please use the ctor with value, name, destructor args")
+ capsule(const void *value, PyCapsule_Destructor destructor)
+ : object(PyCapsule_New(const_cast<void *>(value), nullptr, destructor), stolen_t{}) {
  if (!m_ptr) {
  throw error_already_set();
  }