From 21094e11075fb3bc08b572bd255d099b043dcdfa Mon Sep 17 00:00:00 2001
From: jjrv <juha@busfaster.com>
Date: Sun, 28 Jan 2018 15:44:48 +0200
Subject: [PATCH] Update documentation and copyright.

---
 LICENSE           |  2 +-
 README.md         | 52 +++++++++++++++++++++++++++++++++++++++++++----
 src/classy-mst.ts |  2 +-
 src/index.ts      |  2 +-
 4 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/LICENSE b/LICENSE
index 73d51e3..a904b83 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 BusFaster Ltd
+Copyright (c) 2017-2018 BusFaster Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index 3e7fdbe..8f96bd1 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ class TodoCode extends shim(TodoData) {
 
 }
 
-const Todo = mst(TodoCode, TodoData);
+const Todo = mst(TodoCode, TodoData, 'Todo');
 ```
 
 ES6 methods become views (assumed to have no side-effects) unless decorated
@@ -67,9 +67,13 @@ a block of code with methods (views and actions) to use with the type.
 
 The `mst` function binds the two together (producing a new type "inheriting"
 `TodoData`), and the `TodoCode` class should not be used directly.
+A third, optional parameter gives the resulting model a name.
+Names are required for polymorphism to work correctly, when serializing
+models to JSON containing fields supporting different possible subclasses.
 
 The `shim` function is a tiny wrapper that makes TypeScript accept MST types
-as superclasses.
+as superclasses. It must be used in the `extends` clause of the ES6 class
+defining the views and actions.
 
 The major differences compared to ordinary ES6 classes are:
 
@@ -112,13 +116,53 @@ class SpecialTodoCode extends shim(SpecialTodoData, Todo) {
 
 }
 
-const SpecialTodo = mst(SpecialTodoCode, SpecialTodoData);
+const SpecialTodo = mst(SpecialTodoCode, SpecialTodoData, 'SpecialTodo');
 ```
 
 If adding new properties to the superclass, it's important to pass the
 unmodified superclass as the second parameter to `shim` so that
 `super` is initialized correctly.
 
+Polymorphism
+------------
+
+Instances of subclasses can be used in place of their parent classes inside models.
+Due to `mobx-state-tree` implementation internals, both classes must have been defined
+before the first parent class instance has been created anywhere in the program.
+
+Snapshots containing polymorphic types require type names in the serialized JSON,
+to identify the correct subclass when applying the snapshot.
+A special key `$` is automatically added in snapshots when an object in the tree
+belongs to a subclass of the class actually defined in the model.
+
+The default key `$` for types can be changed by passing a different string to the
+`setTypeTag` function before creating any model instances. For example:
+
+```TypeScript
+import { getSnapshot } from 'mobx-state-tree';
+import { setTypeTag } from 'classy-mst';
+
+setTypeTag('type');
+
+const Store = types.model({
+	todos: types.array(Todo)
+});
+
+const store = Store.create({
+	todos: [
+		SpecialTodo.create({ title: 'Baz' })
+	]
+});
+
+console.log(getSnapshot(store));
+```
+
+The above prints:
+
+```
+{ todos: [ { title: 'Baz', done: false, count: 0, type: 'SpecialTodo' } ] }
+```
+
 Volatile state
 --------------
 
@@ -273,4 +317,4 @@ License
 
 [The MIT License](https://raw.githubusercontent.com/charto/classy-mst/master/LICENSE)
 
-Copyright (c) 2017 BusFaster Ltd
+Copyright (c) 2017-2018 BusFaster Ltd
diff --git a/src/classy-mst.ts b/src/classy-mst.ts
index a20a5a5..fd8a6f9 100644
--- a/src/classy-mst.ts
+++ b/src/classy-mst.ts
@@ -1,4 +1,4 @@
-// This file is part of classy-mst, copyright (c) 2017 BusFaster Ltd.
+// This file is part of classy-mst, copyright (c) 2017-2018 BusFaster Ltd.
 // Released under the MIT license, see LICENSE.
 
 import { IType, IModelType, IStateTreeNode, types } from 'mobx-state-tree';
diff --git a/src/index.ts b/src/index.ts
index a435a32..7a5affd 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,4 +1,4 @@
-// This file is part of classy-mst, copyright (c) 2017 BusFaster Ltd.
+// This file is part of classy-mst, copyright (c) 2017-2018 BusFaster Ltd.
 // Released under the MIT license, see LICENSE.
 
 export { mst, shim, action, setTypeTag, ModelInterface } from './classy-mst';