Issue #838: Clarify use of PureComponent and memo in changelog (#842)

* Issue #838: Clarify use of PureComponent and memo in changelog

* Improve changelog  and readme docs

* Feedback.  Lowercase observer in readme, better changelog link, shouldComponent update to lowercase as well.

* Add 'the' before observer

* Update README.md

Co-Authored-By: Veniamin Krol <[email protected]>

Co-authored-by: Daniel K. <[email protected]>
Co-authored-by: Veniamin Krol <[email protected]>

CHANGELOG.md

@@ -74,7 +74,7 @@
 **Improvements**
 
 -   Hook based components are now supported by mobx-react (in fact, the package is now implemented using hooks)
--   Using `PureComponent` is now _recommended_ for class-based components or `React.memo` for functional ones.
+-   Class based `observer` components are now _recommended_ to extend `React.PureComponent`. Functional `observer` components are now automatically wrapped in `React.memo` internally. See section in [README](https://mobx.js.org/README.html#observercomponentclass) for more details.
 -   For `observer` based components, there will now be an additional `Observer` component in the tree.
 -   Two new hooks have been exposed, in case you want to manage local state in observable: `useLocalStore` and `useAsObservableSource`.
 -   `MobXProviderContext` is now exposed from the package, in case you want to consume the context used by `Provider` with a `useContext` hook.

README.md

@@ -51,12 +51,19 @@ For greenfield projects you might want to consider to use [mobx-react-lite](http
 
 Please check [mobx.js.org](https://mobx.js.org) for the general documentation. The documentation below highlights some specifics.
 
-### `observer(componentClass)`
+### `observer(component)`
 
-Function (and decorator) that converts a React component definition, React component class or stand-alone render function into a reactive component, which tracks which observables are used by `render` and automatically re-renders the component when one of these values changes.
+Function (and decorator) that converts a React component definition, React component class, or stand-alone render function, into a reactive component. A converted component will track which observables are used by its effective `render` and automatically re-render the component when one of these values changes.
+
+#### Functional Components
+
+`React.memo` is automatically applied to functional components provided to `observer`. `observer` does not accept a functional component already wrapped in `React.memo`, or an `observer`, in order to avoid consequences that might arise as a result of wrapping it twice.
+
+#### Class Components
 
 When using component classes, `this.props` and `this.state` will be made observables, so the component will react to all changes in props and state that are used by `render`.
-Note that `observer` automatically applies `React.memo` to any functional component you pass to it, however class components should extend `PureComponent` instead of `Component`
+
+`shouldComponentUpdate` is not supported. As such, it is recommended that class components extend `React.PureComponent`. The `observer` will automatically patch non-pure class components with an internal implementation of `React.PureComponent` if necessary.
 
 See the [MobX](https://mobxjs.github.io/mobx/refguide/observer-component.html) documentation for more details.
 

src/observer.tsx

@@ -27,7 +27,7 @@ export function observer<T extends IReactComponent>(component: T): T {
 
     if (ReactMemoSymbol && component["$$typeof"] === ReactMemoSymbol) {
         throw new Error(
-            "Mobx observer: You are trying to use 'observer' on function component wrapped to either another observer or 'React.memo'. The observer already applies 'React.memo' for you."
+            "Mobx observer: You are trying to use 'observer' on a function component wrapped in either another observer or 'React.memo'. The observer already applies 'React.memo' for you."
         )
     }