[IMP] reactivity: introduces markRaw and toRaw functions

doc/readme.md

@@ -7,9 +7,14 @@ Main entities:
 - [`App`](reference/app.md): represent an Owl application (mainly a root component,a set of templates, and a config)
 - [`Component`](reference/component.md): the main class to define a concrete Owl component
 - [`mount`](reference/app.md#mount-helper): main entry point for most application: mount a component to a target
+- [`xml`](reference/templates.md#inline-templates): helper to define an inline template
+
+Reactivity
+
 - [`useState`](reference/reactivity.md#usestate): create a reactive object (hook, linked to a specific component)
 - [`reactive`](reference/reactivity.md#reactive): create a reactive object (not linked to any component)
-- [`xml`](reference/templates.md#inline-templates): helper to define an inline template
+- [`markRaw`](reference/reactivity.md#markraw): mark an object or array so that it is ignored by the reactivity system
+- [`toRaw`](reference/reactivity.md#toraw): given a reactive objet, return the raw (non reactive) underlying object
 
 Lifecycle hooks:
 

doc/reference/reactivity.md

@@ -5,6 +5,8 @@
 - [Overview](#overview)
 - [`useState`](#usestate)
 - [`reactive`](#reactive)
+- [`markRaw`](#markraw)
+- [`toRaw`](#toraw)
 
 ## Overview
 
@@ -78,3 +80,40 @@ obj2.b = 3; // log 'observer1' and 'observer2'
 
 Obviously, one can use `reactive` on the result of a `useState` if wanted, this
 is the proper way to watch for some state changes.
+
+## `markRaw`
+
+Marks an object so that it is ignored by the reactivity system. This function returns its argument.
+
+```js
+const someObject = markRaw(...);
+const state = useState({
+  a: 1,
+  obj: someObject
+});
+// here, state.obj === someObject
+```
+
+This is useful in some rare cases. For example, some complex and large object such
+that going through the reactivity system may cause a non trivial performance slowdown.
+
+However, use this function with caution: this is an escape hatch from the reactivity
+system, and as such, using it may cause subtle and unintended issues!
+
+## `toRaw`
+
+Given a reactive object, this function returns the underlying, non-reactive,
+corresponding object.
+
+```js
+// in setup
+const state = useState({ value: 1 });
+
+// later:
+const rawState = toRaw(this.state);
+rawState.value = 3; // will NOT be picked up by the reactivity system!!!
+```
+
+Here again, this is useful in some situations where we want to explicitely bypass
+Owl, but using this function means that the responsability of coordinating
+state update is given to the user code, instead of Owl. Subtle bugs may arise!