Doc improvements (#2725)

mweststrate · web-flow · commit 4ebf596eef10 · 2021-01-23T20:41:40.000Z
* docs: Document enumerability as discussed in #2641 * docs: Document `proxy` option as discussed in #2717 * docs: use absolute urls in Readme, fixes #2685 * Add changeset * Name fix
diff --git a/.changeset/rude-berries-stare.md b/.changeset/rude-berries-stare.md
@@ -0,0 +1,5 @@
+---
+
+---
+
+Several documentation improvements, fixes #2685.  
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-<img src="docs/assets/mobx.png" alt="logo" height="120" align="right" />
+<img src="https://mobx.js.org/docs/assets/mobx.png" alt="logo" height="120" align="right" />
 
 # MobX
 
@@ -13,32 +13,32 @@ _Simple, scalable state management._
 
 ---
 
-> Documentation for older __unsupported__ V4/V5 can be [found here](https://github.com/mobxjs/mobx/blob/mobx4and5/docs/README.md), but be sure to read about [current documentation first](https://mobx.js.org/about-this-documentation.html).
+> Documentation for older **unsupported** V4/V5 can be [found here](https://github.com/mobxjs/mobx/blob/mobx4and5/docs/README.md), but be sure to read about [current documentation first](https://mobx.js.org/about-this-documentation.html).
 
 MobX is made possible by the generosity of the sponsors below, and many other [individual backers](docs/backers-sponsors.md#backers). Sponsoring directly impacts the longevity of this project.
 
 **🥇Gold sponsors (\$3000+ total contribution):** <br/>
-<a href="https://mendix.com/"><img src="docs/assets/mendix-logo.png" align="center" width="100" title="Mendix" alt="Mendix" /></a>
-<a href="https://frontendmasters.com/"><img src="docs/assets/frontendmasters.jpg" align="center" width="100" title="Frontend Masters" alt="Frontend Masters"></a>
-<a href="https://opensource.facebook.com/"><img src="docs/assets/fbos.jpeg" align="center" width="100" title="Facebook Open Source" alt="Facebook Open Source" /></a>
-<a href="http://auctionfrontier.com/"><img src="docs/assets/auctionfrontier.jpeg" align="center" width="100" title="Auction Frontier" alt="Auction Frontier"></a>
-<a href="https://www.guilded.gg/"><img src="docs/assets/guilded.jpg" align="center" width="100" title="Guilded" alt="Guilded" /></a>
-<a href="https://coinbase.com/"><img src="docs/assets/coinbase.jpeg" align="center" width="100" title="Coinbase" alt="Coinbase" /></a>
-<a href="https://www.canva.com/"><img src="docs/assets/canva.png" align="center" width="100" title="Canva" alt="Canva" /></a>
+<a href="https://mendix.com/"><img src="https://mobx.js.org/docs/assets/mendix-logo.png" align="center" width="100" title="Mendix" alt="Mendix" /></a>
+<a href="https://frontendmasters.com/"><img src="https://mobx.js.org/docs/assets/frontendmasters.jpg" align="center" width="100" title="Frontend Masters" alt="Frontend Masters"></a>
+<a href="https://opensource.facebook.com/"><img src="https://mobx.js.org/docs/assets/fbos.jpeg" align="center" width="100" title="Facebook Open Source" alt="Facebook Open Source" /></a>
+<a href="http://auctionfrontier.com/"><img src="https://mobx.js.org/docs/assets/auctionfrontier.jpeg" align="center" width="100" title="Auction Frontier" alt="Auction Frontier"></a>
+<a href="https://www.guilded.gg/"><img src="https://mobx.js.org/docs/assets/guilded.jpg" align="center" width="100" title="Guilded" alt="Guilded" /></a>
+<a href="https://coinbase.com/"><img src="https://mobx.js.org/docs/assets/coinbase.jpeg" align="center" width="100" title="Coinbase" alt="Coinbase" /></a>
+<a href="https://www.canva.com/"><img src="https://mobx.js.org/docs/assets/canva.png" align="center" width="100" title="Canva" alt="Canva" /></a>
 
 **🥈Silver sponsors (\$100+ pm):**<br/>
-<a href="https://www.codefirst.co.uk/"><img src="docs/assets/codefirst.png" align="center" width="100" title="CodeFirst" alt="CodeFirst"/></a>
-<a href="https://www.dcslsoftware.com/"><img src="docs/assets/dcsl.png" align="center" width="100" title="DCSL Software" alt="DCSL Software"/></a>
-<a href="https://www.bugsnag.com/platforms/react-error-reporting?utm_source=MobX&utm_medium=Website&utm_content=open-source&utm_campaign=2019-community&utm_term=20190913"><img src="docs/assets/bugsnag.jpg" align="center" width="100" title="Bugsnag" alt="Bugsnag"/></a>
-<a href="https://curology.com/blog/tech"><img src="docs/assets/curology.png" align="center" width="100" title="Curology" alt="Curology"/></a>
-<a href="https://modulz.app/"><img src="docs/assets/modulz.png" align="center" width="100" title="Modulz" alt="Modulz"/></a>
+<a href="https://www.codefirst.co.uk/"><img src="https://mobx.js.org/docs/assets/codefirst.png" align="center" width="100" title="CodeFirst" alt="CodeFirst"/></a>
+<a href="https://www.dcslsoftware.com/"><img src="https://mobx.js.org/docs/assets/dcsl.png" align="center" width="100" title="DCSL Software" alt="DCSL Software"/></a>
+<a href="https://www.bugsnag.com/platforms/react-error-reporting?utm_source=MobX&utm_medium=Website&utm_content=open-source&utm_campaign=2019-community&utm_term=20190913"><img src="https://mobx.js.org/docs/assets/bugsnag.jpg" align="center" width="100" title="Bugsnag" alt="Bugsnag"/></a>
+<a href="https://curology.com/blog/tech"><img src="https://mobx.js.org/docs/assets/curology.png" align="center" width="100" title="Curology" alt="Curology"/></a>
+<a href="https://modulz.app/"><img src="https://mobx.js.org/docs/assets/modulz.png" align="center" width="100" title="Modulz" alt="Modulz"/></a>
 
 **🥉Bronze sponsors (\$500+ total contributions):**<br/>
-<a href="https://mantro.net/jobs/warlock"><img src="docs/assets/mantro.png" align="center" width="100" title="mantro GmbH" alt="mantro GmbH"></a>
-<a href="https://www.algolia.com/"><img src="docs/assets/algolia.jpg" align="center" width="100" title="Algolia" alt="Algolia" /></a>
-<a href="https://talentplot.com/"><img src="docs/assets/talentplot.png" align="center" width="100" title="talentplot" alt="talentplot"></a>
-<a href="https://careers.dazn.com/"><img src="docs/assets/dazn.png" align="center" width="100" title="DAZN" alt="DAZN"></a>
-<a href="https://blokt.com/"><img src="docs/assets/blokt.jpg" align="center" width="100" title="Blokt" alt="Blokt"/></a>
+<a href="https://mantro.net/jobs/warlock"><img src="https://mobx.js.org/docs/assets/mantro.png" align="center" width="100" title="mantro GmbH" alt="mantro GmbH"></a>
+<a href="https://www.algolia.com/"><img src="https://mobx.js.org/docs/assets/algolia.jpg" align="center" width="100" title="Algolia" alt="Algolia" /></a>
+<a href="https://talentplot.com/"><img src="https://mobx.js.org/docs/assets/talentplot.png" align="center" width="100" title="talentplot" alt="talentplot"></a>
+<a href="https://careers.dazn.com/"><img src="https://mobx.js.org/docs/assets/dazn.png" align="center" width="100" title="DAZN" alt="DAZN"></a>
+<a href="https://blokt.com/"><img src="https://mobx.js.org/docs/assets/blokt.jpg" align="center" width="100" title="Blokt" alt="Blokt"/></a>
 
 ---
 
@@ -131,7 +131,7 @@ depends on the `timer.secondsPassed` observable, even though this relationship i
 Every event (`onClick` / `setInterval`) invokes an _action_ (`myTimer.increase` / `myTimer.reset`) that updates _observable state_ (`myTimer.secondsPassed`).
 Changes in the observable state are propagated precisely to all _computations_ and _side effects_ (`TimerView`) that depend on the changes being made.
 
-<img alt="MobX unidirectional flow" src="docs/assets/flow2.png" align="center" />
+<img alt="MobX unidirectional flow" src="https://mobx.js.org/docs/assets/flow2.png" align="center" />
 
 This conceptual picture can be applied to the above example, or any other application using MobX.
 
@@ -160,7 +160,7 @@ The philosophy and benefits of the mental model provided by MobX are also descri
 
 ### The MobX book
 
-[<img src="docs/assets/book.jpg" height="80px"/> ](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false)
+[<img src="https://mobx.js.org/docs/assets/book.jpg" height="80px"/> ](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false)
 
 Created by [Pavan Podila](https://twitter.com/pavanpodila) and [Michel Weststrate](https://twitter.com/mweststrate).
 
diff --git a/docs/actions.md b/docs/actions.md
@@ -22,7 +22,7 @@ MobX requires that you declare your actions, although [`makeAutoObservable`](obs
 
 2. By default, it is not allowed to change the state outside of actions. This helps to clearly identify in your code base where the state updates happen.
 
-The `action` annotation should only be used on functions that intend to _modify_ the state. Functions that derive information (performing lookups or filtering data) should _not_ be marked as actions, to allow MobX to track their invocations.
+The `action` annotation should only be used on functions that intend to _modify_ the state. Functions that derive information (performing lookups or filtering data) should _not_ be marked as actions, to allow MobX to track their invocations. `action` annotated members will be non-enumerable.
 
 ## Examples
 
@@ -258,19 +258,16 @@ class Store {
     fetchProjects() {
         this.githubProjects = []
         this.state = "pending"
-        fetchGithubProjectsSomehow().then(
-            this.projectsFetchSuccess,
-            this.projectsFetchFailure
-        )
+        fetchGithubProjectsSomehow().then(this.projectsFetchSuccess, this.projectsFetchFailure)
     }
 
-    projectsFetchSuccess = (projects) => {
+    projectsFetchSuccess = projects => {
         const filteredProjects = somePreprocessing(projects)
         this.githubProjects = filteredProjects
         this.state = "done"
     }
 
-    projectsFetchFailure = (error) => {
+    projectsFetchFailure = error => {
         this.state = "error"
     }
 }
@@ -373,7 +370,7 @@ Note that the `flowResult` function is only needed when using TypeScript.
 Since decorating a method with `flow`, it will wrap the returned generator in a promise.
 However, TypeScript isn't aware of that transformation, so `flowResult` will make sure that TypeScript is aware of that type change.
 
-`makeAutoObservable` and friends will automatically infer generators to be `flow`s.
+`makeAutoObservable` and friends will automatically infer generators to be `flow`s. `flow` annotated members will be non-enumerable.
 
 <details id="flow-wrap"><summary>{🚀} **Note:** using flow on object fields<a href="#flow-wrap" class="tip-anchor"></a></summary>
 `flow`, like `action`, can be used to wrap functions directly. The above example could also have been written as follows:
diff --git a/docs/observable-state.md b/docs/observable-state.md
@@ -237,6 +237,7 @@ The above APIs take an optional `options` argument which is an object that suppo
 -   `autoBind: true` automatically binds all created actions to the instance.
 -   `deep: false` uses `observable.ref` by default, rather than `observable` to create new observable members.
 -   `name: <string>` gives the object a debug name that is printed in error messages and reflection APIs.
+-   `proxy: false` skips Proxy creating. This is a good option if the shape of the object will not change over time, as non-proxied objects are easier to debug and faster. See [avoiding proxies](#avoid-proxies).
 
 ## Converting observables back to vanilla JavaScript collections
 

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
++
 +---
++
 +Several documentation improvements, fixes #2685.