Revise changelog

Author: japgolly

doc/changelog/1.7.0.md

@@ -90,12 +90,8 @@ This is a big release with big release notes. Grab a coffee and enjoy!
 
 * **Bugfix**: `setState(newState: S, callback: Callback)` wasn't calling the specified `Callback` (!!!)
 
-* Added async versions of all `{set,mod}State` functions that return `AsyncCallback`s that resume when React has
-  finished applying the state change.
-
-  If you write a callback that must be executed after a state update, you would've learned that `setState(s) >> c`
-  would be a bug because React applies state changes asynchronously. The correct way of writing it would be
-  `setState(s, c)`. With this change you could now also write `setStateAsync(s) >> c.toAsyncCallback`.
+* Added async versions of all `{set,mod}State` functions.
+  These return `AsyncCallback`s that resume when React has finished applying the state change.
 
   ```scala
   .setStateAsync(S)                        : AsyncCallback[Unit]
@@ -106,11 +102,17 @@ This is a big release with big release notes. Grab a coffee and enjoy!
   .modStateOptionAsync((S, P) => Option[S]): AsyncCallback[Unit]
   ```
 
+  If you write a callback that must be executed after a state update, you would've learned that `setState(s) >> c`
+  would be a bug because React applies state changes asynchronously. The correct way of writing it would be
+  `setState(s, c)`. With this change you could now also write `setStateAsync(s) >> c.toAsyncCallback`.
+
 * Made `Callback(To)` and `AsyncCallback` stack-safe
 
 * Added to `AsyncCallback[A]`:
   * `def sync: CallbackTo[Either[AsyncCallback[A], A]]` to turn a `AsyncCallback` into a synchronous `Callback` when possible
-  * `def unsafeRunNowSync(): A` for unit testing
+  * `def unsafeRunNowSync(): A` which is handy in unit tests where you've taken care to ensure that test code provides
+    `AsyncCallback`s that are actually synchronous under the hood. (eg. instead of a real async AJAX call your test provides
+    an `AsyncCallback` that returns a test response immediately)
   * `def delay[A](a: => A): AsyncCallback[A]` and deprecate `.point`
   * versions of existing methods that `AsyncCallback` arguments, to take `CallbackTo` instances instead:
     ```scala
@@ -140,22 +142,31 @@ This is a big release with big release notes. Grab a coffee and enjoy!
 
 * Added to `StateSnapshot[S]`:
   ```scala
-  .narrowOption             [T <: S]                                              : Option[StateSnapshot[T]]
-  .unsafeWiden              [T >: S]                                              : StateSnapshot[T]
-  .zoomStateOption          [T](f: S => Option[T])(g: T => S => S)                : Option[StateSnapshot[T]]
-  .withReuse.zoomStateOption[T](optional: Reusable[(S => Option[T], T => S => S)]): Option[StateSnapshot[T]]
+  /** @return `None` if `value: S` isn't `value: T` as well. */
+  def narrowOption[T <: S]: Option[StateSnapshot[T]]
+
+  /** Unsafe because writes may be dropped.
+    *
+    * Eg. if you widen a `StateSnapshot[Banana]` into `StateSnapshot[Food]`,
+    * calling `setState(banana2)` will work but `setState(pasta)` will be silently ignored.
+    */
+  def unsafeWiden[T >: S]: StateSnapshot[T]
+
+  def zoomStateOption[T](f: S => Option[T])(g: T => S => S): Option[StateSnapshot[T]]
+
+  def withReuse.zoomStateOption[T](optional: Reusable[(S => Option[T], T => S => S)]): Option[StateSnapshot[T]]
 
   // If using `import MonocleReact._`
-  .zoomStateO               [B](o: monocle.Optional[A, B])          : Option[StateSnapshot[B]]
-  .withReuse.zoomStateO     [B](o: Reusable[monocle.Optional[A, B]]): Option[StateSnapshot[B]]
+  .zoomStateO          [B](o: monocle.Optional[A, B])          : Option[StateSnapshot[B]]
+  .withReuse.zoomStateO[B](o: Reusable[monocle.Optional[A, B]]): Option[StateSnapshot[B]]
   ```
 
 * Added to `StateSnapshot`:
   * `(value).readOnly` to create a `StateSnapshot` that ignores writes/updates
   * `.withReuse(value).readOnly` to create a `StateSnapshot` that ignores writes/updates
   * `.withReuse.prepareViaProps[P, I]($: GenericComponent.MountedPure[P, _])(f: P => I)`
   * `.withReuse.prepareViaCallback[I](cb: CallbackTo[I])`
-  * [example of how these can be used -- it's the recommended way to handle state with scalajs-react](https://japgolly.github.io/scalajs-react/#examples/state-snapshot-2)
+  * [example of how these can be used -- **this is the recommended way to handle state with scalajs-react**](https://japgolly.github.io/scalajs-react/#examples/state-snapshot-2)
 
 * Changes in `object Reusability`:
   * update `.caseClassExcept` to accept `String` arguments instead of `scala.Symbol`s,
@@ -197,8 +208,7 @@ This is a big release with big release notes. Grab a coffee and enjoy!
 * Testing
   * `ReactTestUtils` methods now only warn when failing to unmount a component, rather than throwing an error
   * Event simulation in tests now ensures that default properties of events are set.
-
-    Example: you don't need to manually specify `defaultPrevented` or `altKey` in a `Simulate.click`, they now default to `false`.
+    <br>Example: you don't need to manually specify `defaultPrevented` or `altKey` in a `Simulate.click`, they now default to `false`.
 
 * `MonocleReact`
   * the `modStateL` and `modStateOptionL` methods now accept all kinds of appropriate optics instead of just lenses