docs: improve messaging around #[pyclass(from_py_object)] change (#5798)

* docs: improve messaging around `#[pyclass(from_py_object)]` change

* fmt

* add justification to deprecation

* fix migration guide entry

Author: davidhewitt

guide/src/migration.md

@@ -22,12 +22,41 @@ Modules now automatically allow use on free-threaded Python, unless they directl
 <summary><small>Click to expand</small></summary>
 
 `#[pyclass]` types which implement `Clone` used to also implement `FromPyObject` automatically.
-This behaviour is phased out and replaced by an explicit opt-in.
+This behavior is being phased out and replaced by an explicit opt-in, which will allow [better error messages and more user control](https://github.com/PyO3/pyo3/issues/5419).
 Affected types will by marked by a deprecation message.
+
 To migrate use either
 
-- `from_py_object` to keep the automatic derive, or
-- `skip_from_py_object` to accept the new behaviour
+- `#[pyclass(from_py_object)]` to keep the automatic derive, or
+- `#[pyclass(skip_from_py_object)]` to accept the new behavior.
+
+Before:
+
+```rust
+# #![allow(deprecated)]
+# use pyo3::prelude::*;
+#[pyclass]
+#[derive(Clone)]
+struct PyClass {}
+```
+
+After:
+
+```rust
+# use pyo3::prelude::*;
+// If the automatic implementation of `FromPyObject` is desired, opt in:
+#[pyclass(from_py_object)]
+#[derive(Clone)]
+struct PyClass {}
+
+// or if the `FromPyObject` implementation is not needed:
+#[pyclass(skip_from_py_object)]
+#[derive(Clone)]
+struct PyClassWithoutFromPyObject {}
+```
+
+The `#[pyclass(skip_from_py_object)]` option will eventually be deprecated and removed as it becomes the default behavior.
+
 </details>
 
 ### Deprecation of `Py<T>` constructors from raw pointer
@@ -44,7 +73,7 @@ These should be used instead.
 Before:
 
 ```rust
-#![allow(deprecated)]
+# #![allow(deprecated)]
 # use pyo3::prelude::*;
 # use pyo3::types::PyNone;
 # Python::attach(|py| {

src/impl_/deprecated.rs

@@ -3,7 +3,7 @@ pub struct HasAutomaticFromPyObject<const IS_CLONE: bool> {}
 impl HasAutomaticFromPyObject<true> {
     #[deprecated(
         since = "0.28.0",
-        note = "The automatically derived `FromPyObject` implementation for `#[pyclass]` types which implement `Clone` is being phased out. Use `from_py_object` to keep the automatic derive or `skip_from_py_object` to accept the new behaviour."
+        note = "The `FromPyObject` implementation for `#[pyclass]` types which implement `Clone` is changing to an opt-in option. Use `#[pyclass(from_py_object)]` to opt-in to the `FromPyObject` derive now, or `#[pyclass(skip_from_py_object)]` to skip the `FromPyObject` implementation."
     )]
     pub const MSG: () = ();
 }

tests/ui/invalid_pyclass_args.stderr

@@ -443,7 +443,7 @@ error[E0609]: no field `162543` on type `&Coord3`
     |
     = note: available fields are: `0`, `1`, `2`
 
-warning: use of deprecated associated constant `pyo3::impl_::deprecated::HasAutomaticFromPyObject::<true>::MSG`: The automatically derived `FromPyObject` implementation for `#[pyclass]` types which implement `Clone` is being phased out. Use `from_py_object` to keep the automatic derive or `skip_from_py_object` to accept the new behaviour.
+warning: use of deprecated associated constant `pyo3::impl_::deprecated::HasAutomaticFromPyObject::<true>::MSG`: The `FromPyObject` implementation for `#[pyclass]` types which implement `Clone` is changing to an opt-in option. Use `#[pyclass(from_py_object)]` to opt-in to the `FromPyObject` derive now, or `#[pyclass(skip_from_py_object)]` to skip the `FromPyObject` implementation.
    --> tests/ui/invalid_pyclass_args.rs:196:1
     |
 196 | #[pyclass]