Docs: Promote the createRef api to be the more favored mode of ref cr…

…eation (#108)

docs/advanced/refs.md

@@ -16,43 +16,40 @@ For example, suppose we wanted to create a search bar that captured cursor focus
  ]]
 local SearchBar = Roact.Component:extend("SearchBar")
 
+function SearchBar:init()
+	self.textBoxRef = Roact.createRef()
+end
+
 function SearchBar:render()
 	-- Render our icon and text box side by side in a Frame
 	return Roact.createElement("Frame", {
 		Size = UDim2.new(0, 200, 0, 20),
 	}, {
 		SearchIcon = Roact.createElement("ImageButton", {
 			Size = UDim2.new(0, 20, 0, 20),
-			-- Handle click events on the icon
-			[Roact.Event.MouseButton1Click] = function()
 
-				-- If our capture method is defined, trigger it
-				if self.captureTextboxFocus then
-					self.captureTextboxFocus()
-				end
+			-- Handle click events on the icon
+			[Roact.Event.Activated] = function()
+				self.textBoxRef.current:CaptureFocus()
 			end
 		}),
 
 		SearchTextBox = Roact.createElement("TextBox", {
 			Size = UDim2.new(0, 180, 0, 20),
 			Position = UDim2.new(0, 20, 0, 0),
-			-- We use Roact.Ref to get a reference to the underlying object
-			[Roact.Ref] = function(rbx)
 
-				-- Set a callback function to give focus to the TextBox
-				self.captureTextboxFocus = function()
-					rbx:CaptureFocus()
-				end
-			end
+			-- Use Roact.Ref to get a reference to the underlying object
+			[Roact.Ref] = self.textBoxRef
 		}),
 	})
 end
 ```
 When a user clicks on the outer `ImageButton`, the `captureTextboxFocus` callback will be triggered and the `TextBox` instance will get focus as if it had been clicked on directly.
 
-## Refs During Teardown
+## Refs During Unmount
+
 !!! warning
-	When a component instance is destroyed or the ref property changes, `nil` will be passed to the old ref function!
+	When using the function version of refs, any time a component instance is destroyed or the ref property changes, `nil` will be passed to the old ref function!
 
 ```lua
 local frame = Roact.createElement("Frame", {

docs/api-reference.md

@@ -78,17 +78,7 @@ If you're writing a new functional or stateful element that needs to be used lik
 ### Roact.Ref
 Use `Roact.Ref` as a key into the props of a primitive element to receive a handle to the underlying Roblox Instance.
 
-`Ref` may either be a function:
-```lua
-Roact.createElement("Frame", {
-	-- The function given will be called whenever the rendered instance changes.
-	[Roact.Ref] = function(rbx)
-		print("Roblox Instance", rbx)
-	end,
-})
-```
-
-Or a reference object created with [createRef](#roactcreateref):
+Assign this key to a reference object created with [createRef](#roactcreateref):
 ```lua
 local ExampleComponent = Roact.Component:extend("ExampleComponent")
 
@@ -100,7 +90,7 @@ end
 function ExampleComponent:render()
 	return Roact.createElement("Frame", {
 		-- Use the reference object to point to this rendered instance.
-		[Roact.Ref] = ref,
+		[Roact.Ref] = self.ref,
 	})
 end
 
@@ -110,8 +100,21 @@ function ExampleComponent:didMount()
 end
 ```
 
+Alternatively, you can assign it to a function instead:
+```lua
+Roact.createElement("Frame", {
+	-- The provided function will be called whenever the rendered instance changes.
+	[Roact.Ref] = function(rbx)
+		print("Roblox Instance", rbx)
+	end,
+})
+```
+
+!!! warning
+	When `Roact.Ref` is given a funciton, Roact does not guarantee when this function will be run relative to the reconciliation of other props. If you try to read a Roblox property that's being set via a Roact prop, you won't know if you're reading it before or after Roact reconciles that prop!
+
 !!! warning
-	`Roact.Ref` will be called with `nil` when the component instance is destroyed!
+	When `Roact.Ref` is given a funciton, it will be called with `nil` when the component instance is destroyed!
 
 See [the refs guide](/advanced/refs.md) for more details.