Clarify refs and setState callback documentation

(cherry picked from commit 121b290)

Author: sophiebits

docs/docs/07.1-more-about-refs.md

@@ -72,17 +72,19 @@ React supports a very special property that you can attach to any component that
 
 It's as simple as:
 
-**1.** Assign a `ref` attribute to anything returned from `render` such as:
+1. Assign a `ref` attribute to anything returned from `render` such as:
 
-```html
-   <input ref="myInput" />
-```
+  ```html
+  <input ref="myInput" />
+  ```
 
-**2.** In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
+2. In some other code (typically event handler code), access the **backing instance** via `this.refs` as in:
 
-```javascript
+  ```javascript
   this.refs.myInput
-```
+  ```
+
+  You can access the component's DOM node directly by calling `this.refs.myInput.getDOMNode()`.
 
 ## Completing the Example
 
@@ -95,8 +97,11 @@ It's as simple as:
       this.setState({userInput: e.target.value});
     },
     clearAndFocusInput: function() {
-      this.setState({userInput: ''}); // Clear the input
-      this.refs.theInput.getDOMNode().focus();   // Boom! Focused!
+      // Clear the input
+      this.setState({userInput: ''}, function() {
+        // This code executes after the component is re-rendered
+        this.refs.theInput.getDOMNode().focus();   // Boom! Focused!
+      });
     },
     render: function() {
       return (
@@ -132,4 +137,4 @@ Refs are a great way to send a message to a particular child instance in a way t
 
 - *Never* access refs inside of any component's render method - or while any component's render method is even running anywhere in the call stack.
 - If you want to preserve Google Closure Compiler Crushing resilience, make sure to never access as a property what was specified as a string. This means you must access using `this.refs['myRefString']` if your ref was defined as `ref="myRefString"`.
-- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" - instead, the data flow will usually accomplish your goal.
+- If you have not programmed several apps with React, your first inclination is usually going to be to try to use refs to "make things happen" in your app. If this is the case, take a moment and think more critically about where `state` should be owned in the component hierarchy. Often, it becomes clear that the proper place to "own" that state is at a higher level in the hierarchy. Placing the state there often eliminates any desire to use `ref`s to "make things happen" – instead, the data flow will usually accomplish your goal.

docs/docs/ref-02-component-api.md

@@ -29,7 +29,7 @@ setProps(object nextProps[, function callback])
 
 When you're integrating with an external JavaScript application you may want to signal a change to a React component rendered with `React.renderComponent()`.
 
-Though calling `React.renderComponent()` again on the same node is the preferred way to update a root-level component, you can also call `setProps()` to change its properties and trigger a re-render. In addition, you can supply an optional callback function that is executed once `setProps` is completed.
+Though calling `React.renderComponent()` again on the same node is the preferred way to update a root-level component, you can also call `setProps()` to change its properties and trigger a re-render. In addition, you can supply an optional callback function that is executed once `setProps` is completed and the component is re-rendered.
 
 > Note:
 >
@@ -80,7 +80,7 @@ Properties that are specified directly on the target component instance (such as
 setState(object nextState[, function callback])
 ```
 
-Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks.  In addition, you can supply an optional callback function that is executed once `setState` is completed.
+Merges nextState with the current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks.  In addition, you can supply an optional callback function that is executed once `setState` is completed and the component is re-rendered.
 
 > Notes:
 >