Rename reify to mount and teardown to unmount (#85)

This introduces ReconcilerCompat, which provides warning-enabled versions of the original methods, `reify` and `teardown` that are aliases to the new ones.

CHANGELOG.md

@@ -1,6 +1,8 @@
 # Roact Changelog
 
 ## Current `master` branch
+* Renamed `Roact.reify` to `Roact.mount` and `Roact.teardown` to `Roact.unmount` ([#82](https://github.com/Roblox/roact/issues/82))
+	* The old methods are still present as aliases, but will output a warning when used.
 * Added `Roact.Change` for subscribing to `GetPropertyChangedSignal` ([#51](https://github.com/Roblox/roact/pull/51))
 * Added the static lifecycle method `getDerivedStateFromProps` ([#57](https://github.com/Roblox/roact/pull/57))
 * Allow canceling render by returning nil from setState callback ([#64](https://github.com/Roblox/roact/pull/64))

README.md

@@ -45,7 +45,7 @@ local tree = Roact.createElement("ScreenGui", {}, {
 })
 
 -- Turn our virtual tree into real instances and put them in PlayerGui
-Roact.reify(tree, LocalPlayer.PlayerGui, "HelloWorld")
+Roact.mount(tree, LocalPlayer.PlayerGui, "HelloWorld")
 ```
 
 ## License

benchmarks/hello.bench.lua

@@ -7,7 +7,7 @@ return {
 			Value = "Hello, world!",
 		})
 
-		local handle = Roact.reify(hello)
-		Roact.teardown(handle)
+		local handle = Roact.mount(hello)
+		Roact.unmount(handle)
 	end,
 }

benchmarks/reconcile.bench.lua

@@ -5,12 +5,12 @@ local handle
 return {
 	iterations = 100000,
 	setup = function()
-		handle = Roact.reify(Roact.createElement("StringValue", {
+		handle = Roact.mount(Roact.createElement("StringValue", {
 			Value = "Initial",
 		}))
 	end,
 	teardown = function()
-		Roact.teardown(handle)
+		Roact.unmount(handle)
 	end,
 	step = function(i)
 		handle = Roact.reconcile(handle, Roact.createElement("StringValue", {

docs/advanced/refs.md

@@ -61,12 +61,12 @@ local frame = Roact.createElement("Frame", {
 	end
 })
 
-local handle = Roact.reify(frame)
+local handle = Roact.mount(frame)
 
 -- Output:
 --     Ref was called with Frame of type Instance
 
-Roact.teardown(handle)
+Roact.unmount(handle)
 
 -- In the output:
 --     Ref was called with nil of type nil

docs/api-reference.md

@@ -16,14 +16,17 @@ The `children` argument is shorthand for adding a `Roact.Children` key to `props
 !!! caution
 	Once `props` or `children` are passed into the `createElement`, make sure not to modify them!
 
-### Roact.reify
+### Roact.mount
 ```
-Roact.reify(element, [parent, [key]]) -> ComponentInstanceHandle
+Roact.mount(element, [parent, [key]]) -> ComponentInstanceHandle
 ```
 
+!!! warning
+	`Roact.mount` is also available via the deprecated alias `Roact.reify`. It will be removed in a future release.
+
 Creates a Roblox Instance given a Roact element, and optionally a `parent` to put it in, and a `key` to use as the instance's `Name`.
 
-The result is a `ComponentInstanceHandle`, which is an opaque handle that represents this specific instance of the root component. You can pass this to APIs like `Roact.teardown` and the future debug API.
+The result is a `ComponentInstanceHandle`, which is an opaque handle that represents this specific instance of the root component. You can pass this to APIs like `Roact.unmount` and the future debug API.
 
 ### Roact.reconcile
 ```
@@ -32,19 +35,22 @@ Roact.reconcile(instanceHandle, element) -> ComponentInstanceHandle
 
 Updates an existing instance handle with a new element, returning a new handle.
 
-`reconcile` can be used to change the props of a component instance created with `reify` and is useful for putting Roact content into non-Roact applications.
+`reconcile` can be used to change the props of a component instance created with `mount` and is useful for putting Roact content into non-Roact applications.
 
 !!! warning
-	`Roact.reconcile` takes ownership of the `instanceHandle` passed into it and may tear it down and create a new tree!
+	`Roact.reconcile` takes ownership of the `instanceHandle` passed into it and may unmount it and mount a new tree!
 
-	Make sure to use the handle that `reconcile` returns in any operations after `reconcile`, including `teardown`.
+	Make sure to use the handle that `reconcile` returns in any operations after `reconcile`, including `unmount`.
 
-### Roact.teardown
+### Roact.unmount
 ```
-Roact.teardown(instance) -> void
+Roact.unmount(instance) -> void
 ```
 
-Destroys the given `ComponentInstanceHandle` and all of its descendents. Does not operate on a Roblox Instance -- this must be given a handle that was returned by `Roact.reify`.
+!!! warning
+	`Roact.unmount` is also available via the deprecated alias `Roact.teardown`. It will be removed in a future release.
+
+Destroys the given `ComponentInstanceHandle` and all of its descendents. Does not operate on a Roblox Instance -- this must be given a handle that was returned by `Roact.mount`.
 
 ### Roact.oneChild
 `Roact.oneChild(children) -> RoactElement | nil`
@@ -258,7 +264,7 @@ didMount() -> void
 willUnmount() -> void
 ```
 
-`willUnmount` is fired right before Roact begins tearing down a component instance's children.
+`willUnmount` is fired right before Roact begins unmounting a component instance's children.
 
 `willUnmount` acts like a component's destructor, and is a good place to disconnect any manually-connected events.
 

docs/guide/components.md

@@ -99,7 +99,7 @@ local currentTime = 0
 local clockElement = Roact.createElement(Clock, {
 	currentTime = currentTime
 })
-local handle = Roact.reify(clockElement, PlayerGui, "Clock UI")
+local handle = Roact.mount(clockElement, PlayerGui, "Clock UI")
 
 -- Every second, update the UI to show our new time.
 while true do

docs/guide/elements.md

@@ -23,14 +23,16 @@ local myElement = Roact.createElement("Frame", {
 })
 ```
 
-Creating an element by itself doesn't do anything, however. In order to turn our description of an object into a real Roblox Instance, we can call `Roact.reify`:
+Creating an element by itself doesn't do anything, however. In order to turn our description of an object into a real Roblox Instance, we can call `Roact.mount`:
 
 ```lua
 -- Create a new Frame object in 'Workspace'
-local myHandle = Roact.reify(myElement, game.Workspace)
+local myHandle = Roact.mount(myElement, game.Workspace)
 ```
 
-`Roact.reify` returns a handle that we can later use to update or destroy that object with `Roact.reconcile` and `Roact.teardown`.
+Mounting is the process of creating a Roact component instance as well as any associated Roblox Instances.
+
+`Roact.mount` returns a handle that we can later use to update or destroy that object with `Roact.reconcile` and `Roact.unmount`.
 
 ## Changing What's Rendered
 In order to change the UI that we've created, we need to create a new set of elements and *reconcile* the existing tree to match it.
@@ -60,17 +62,17 @@ myHandle = Roact.reconcile(myHandle, myNewElement)
 
 Unlike many other UI systems, Roact doesn't let you directly set values on UI objects. Instead, describe what your UI should look like in the form of elements and Roact will handle changing the underlying Roblox Instances.
 
-## Destroying the Tree
-Roact provides a method called `Roact.teardown` that we can use when we're finished with our tree.
+## Unmounting the Tree
+Roact provides a method called `Roact.unmount` that we can use when we're finished with our tree.
 
 ```lua
-Roact.teardown(myHandle)
+Roact.unmount(myHandle)
 ```
 
-!!! warning
-	Once `teardown` is called, all Roblox Instances get destroyed!
+Unmounting destructs the given Roact component instance and destroys any associated Roblox Instances with it.
 
-	Trying to use a handle after it's been passed to `Roact.teardown` will result in errors!
+!!! warning
+	Trying to use a handle after it's been passed to `Roact.unmount` will result in errors!
 
 ## Incrementing Counter
 Using what's been covered so far, we can make a simple program that tells you how long it has been running.
@@ -98,7 +100,7 @@ local PlayerGui = Players.LocalPlayer.PlayerGui
 
 -- Create our initial UI.
 local currentTime = 0
-local handle = Roact.reify(clock(currentTime), PlayerGui, "Clock UI")
+local handle = Roact.mount(clock(currentTime), PlayerGui, "Clock UI")
 
 -- Every second, update the UI to show our new time.
 while true do

docs/guide/hello-roact.md

@@ -18,7 +18,7 @@ local app = Roact.createElement("ScreenGui", {}, {
 	})
 })
 
-Roact.reify(app, Players.LocalPlayer.PlayerGui)
+Roact.mount(app, Players.LocalPlayer.PlayerGui)
 ```
 
 When you run your game, you should see a large gray label with the phrase 'Hello, Roact!' appear on screen!

docs/guide/state-and-lifecycle.md

@@ -85,9 +85,9 @@ end
 local PlayerGui = Players.LocalPlayer.PlayerGui
 
 -- Create our UI, which now runs on its own!
-local handle = Roact.reify(Roact.createElement(Clock), PlayerGui, "Clock UI")
+local handle = Roact.mount(Roact.createElement(Clock), PlayerGui, "Clock UI")
 
 -- Later, we can destroy our UI and disconnect everything correctly.
 wait(10)
-Roact.teardown(handle)
+Roact.unmount(handle)
 ```

docs/images/lifecycle.gv

@@ -12,14 +12,26 @@ digraph G {
 
 	render1 [label="render"];
 	created [style="rounded", color="#000000", label=<<i>Instances created</i>>];
-	reify [style="rounded", color="#000000", label=<<b>Reification</b><br /><br />(Create)>];
-	reify -> init -> render1 -> created -> didMount;
+	mount [style="rounded", color="#000000", label=<
+		<b>Mounting</b>
+		<br /><br />
+		<font face="monospace">Roact.mount</font>
+	>];
+	mount -> init -> render1 -> created -> didMount;
 
 	updated [style="rounded", color="#000000", label=<<i>Instances updated</i>>];
-	reconcile [style="rounded", color="#000000", label=<<b>Reconciliation</b><br /><br />(Update)>];
+	reconcile [style="rounded", color="#000000", label=<
+		<b>Reconciliation</b>
+		<br /><br />
+		<font face="monospace">Roact.reconcile</font>
+	>];
 	reconcile -> shouldUpdate -> getDerivedStateFromProps -> willUpdate -> render -> updated -> didUpdate;
 
 	unmounted [style="rounded", color="#000000", label=<<i>Component Unmounted</i>>];
-	unmount [style="rounded", color="#000000", label=<<b>Unmounting</b><br /><br />(Destroy)>];
+	unmount [style="rounded", color="#000000", label=<
+		<b>Unmounting</b>
+		<br /><br />
+		<font face="monospace">Roact.unmount</font>
+	>];
 	unmount -> willUnmount -> unmounted;
 }