Deprecate pybind11_abseil/status_caster.h, adjust IWYU pragmas accord…

…ingly.

The header was meant to be deprecated for >1 year, but this was not documented.

Also adopt the

```
// IWYU pragma: always_keep // See pybind11/docs/type_caster_iwyu.rst
```

comment used in google/pybind11clif#30073.

Currently pybind11/docs/type_caster_iwyu.rst only exists in google/pybind11clif#30073, but the intend is to upstream the changes (see PR description).

See also: https://clangd.llvm.org/design/include-cleaner

PiperOrigin-RevId: 578314470

pybind11_abseil/absl_casters.h

@@ -27,9 +27,7 @@
 //
 // Author: Ken Oslund
 
-// This header declares template specializations, and thus its use may
-// not be visible to inclusion analysis tools, but we must retain it.
-// IWYU pragma: always_keep
+// IWYU pragma: always_keep // See pybind11/docs/type_caster_iwyu.rst
 
 #ifndef PYBIND11_ABSEIL_ABSL_CASTERS_H_
 #define PYBIND11_ABSEIL_ABSL_CASTERS_H_

pybind11_abseil/status_caster.h

@@ -1,4 +1,7 @@
 // Author: Ken Oslund (kenoslund@)
+
+// IWYU pragma: always_keep // See pybind11/docs/type_caster_iwyu.rst
+
 #ifndef PYBIND11_ABSEIL_STATUS_CASTER_H_
 #define PYBIND11_ABSEIL_STATUS_CASTER_H_
 

pybind11_abseil/status_casters.h

@@ -1,29 +1,10 @@
-// Type conversion utilities for pybind11 and absl::Status/StatusOr.
-//
-// Usage:
-// 1) Include this file in the .cc file with your bindings.
-// 2) Call `pybind11::google::ImportStatusModule()` in your PYBIND11_MODULE
-//    definition.
-//
-// Supported types:
-// - absl::Status- converts a non-ok return status into a python exception.
-//   Can be passed as an argument too if you import the status pybind module.
-// - absl::StatusOr- converts a non-ok return status into a python exception,
-//   otherwise converts/returns the payload. Can only be used as a return value.
-//
-// For details, see the README.md.
-//
-// Author: Ken Oslund (kenoslund@)
-
-// This header declares template specializations, and thus its use may
-// not be visible to inclusion analysis tools, but we must retain it.
-// IWYU pragma: always_keep
+// DEPRECATED: Please prefer including the headers below directly.
 
 #ifndef PYBIND11_ABSEIL_STATUS_CASTERS_H_
 #define PYBIND11_ABSEIL_STATUS_CASTERS_H_
 
-#include "pybind11_abseil/status_caster.h"  // IWYU pragma: export
-#include "pybind11_abseil/statusor_caster.h"  // IWYU pragma: export
-#include "pybind11_abseil/import_status_module.h"  // IWYU pragma: export
+#include "pybind11_abseil/status_caster.h"
+#include "pybind11_abseil/statusor_caster.h"
+#include "pybind11_abseil/import_status_module.h"
 
 #endif  // PYBIND11_ABSEIL_STATUS_CASTERS_H_

pybind11_abseil/statusor_caster.h

@@ -1,4 +1,7 @@
 // Author: Ken Oslund (kenoslund@)
+
+// IWYU pragma: always_keep // See pybind11/docs/type_caster_iwyu.rst
+
 #ifndef PYBIND11_ABSEIL_STATUSOR_CASTER_H_
 #define PYBIND11_ABSEIL_STATUSOR_CASTER_H_