Apply suggestions from code review

Co-Authored-By: David Hewitt <1939362+davidhewitt@users.noreply.github.com>

guide/src/migration.md

@@ -1,10 +1,10 @@
-# Appendix B: Migration Guides for major version changes
-
+# Appendix B: Migrating from older PyO3 versions
+This guide can help you upgrade code through breaking changes from one PyO3 version to the next. For a detailed list of all changes, see [CHANGELOG.md](https://github.com/PyO3/pyo3/blob/master/CHANGELOG.md)
 ## from 0.8.* to 0.9
 
 ### `#[new]` interface
 [`PyRawObject`](https://docs.rs/pyo3/0.8.5/pyo3/type_object/struct.PyRawObject.html)
-is now removed and our syntax for constructor changed.
+is now removed and our syntax for constructors has changed.
 
 Before:
 ```compile_fail
@@ -42,10 +42,11 @@ For more, see [the constructor section](https://pyo3.rs/master/class.html#constr
 PyO3 0.9 introduces [`PyCell`](https://pyo3.rs/master/doc/pyo3/pycell/struct.PyCell.html), which is
 a [`RefCell`](https://doc.rust-lang.org/std/cell/struct.RefCell.html) like object wrapper
 for dynamically ensuring
-[Rust's rule of Reference](https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html#the-rules-of-references).
+[Rust's rules of references](https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html#the-rules-of-references).
 
-For `#[pymethods]` or `#[pyfunction]`s, `PyCell` works without any change.
-Just throw errors when there happens invalid borrowing.
+For `#[pymethods]` or `#[pyfunction]`s, your existing code should continue to work without any change.
+Python exceptions will automatically be raised when your functions are used in a way which breaks Rust's
+rules of references.
 
 Here is an example.
 ```
@@ -78,8 +79,8 @@ impl Names {
 # ");
 ```
 `Names` has `merge` method, which takes `&mut self` and `&mut Self`.
-Given this `#[pyclass]`, calling `names.merge(names)` in Python raises `PyBorrowMutError` exception,
-since it requires two mutable borrows of `names`,
+Given this `#[pyclass]`, calling `names.merge(names)` in Python raises a `PyBorrowMutError` exception,
+since it requires two mutable borrows of `names`.
 
 However, for `#[pyproto]` and some functions, you need to manually fix codes.
 
@@ -110,8 +111,8 @@ let obj_ref = obj.borrow();
 ```
 
 #### Object extraction
-Now for `T: PyClass`, `&T` and `&mut T` don't have `FromPyObject` implementation.
-Instead, you can use `&PyCell`, `PyRef`, and `PyRefMut` for object extraction.
+`T: PyClass`, `&T` and `&mut T` no longer have `FromPyObject` implementations.
+Instead you should extract `&PyCell`, `PyRef`, and `PyRefMut` respectively.
 
 Before:
 ```ignore
@@ -135,7 +136,7 @@ let obj: &PyAny = create_obj();
 let obj_cell: &PyCell<MyClass> = obj.extract().unwrap();
 {
     let obj_ref: PyRef<MyClass> = obj.extract().unwrap();
-    // we need to drop obj_ref before taking RefMut
+    // we need to drop obj_ref before we can extract a PyRefMut due to Rust's rules of references
 }
 let obj_ref_mut: PyRefMut<MyClass> = obj.extract().unwrap();
 ```