Merge pull request #4868 from AnSavvides/docs-readability

Make docs more consistent

docs/ref-02-component-api.md

@@ -14,13 +14,16 @@ Instances of a React Component are created internally in React when rendering. T
 ### setState
 
 ```javascript
-setState(function|object nextState[, function callback])
+setState(
+  function|object nextState,
+  [function callback]
+)
 ```
 Performs a shallow merge of nextState into current state. This is the primary method you use to trigger UI updates from event handlers and server request callbacks.
 
 The first argument can be an object (containing zero or more keys to update) or a function (of state and props) that returns an object containing keys to update.
 
-Here is the simple object usage...
+Here is the simple object usage:
 
 ```javascript
 setState({mykey: 'my new value'});
@@ -50,7 +53,10 @@ The second (optional) parameter is a callback function that will be executed onc
 ### replaceState
 
 ```javascript
-replaceState(object nextState[, function callback])
+replaceState(
+  object nextState,
+  [function callback]
+)
 ```
 
 Like `setState()` but deletes any pre-existing state keys that are not in nextState.
@@ -63,7 +69,9 @@ Like `setState()` but deletes any pre-existing state keys that are not in nextSt
 ### forceUpdate
 
 ```javascript
-forceUpdate([function callback])
+forceUpdate(
+  [function callback]
+)
 ```
 
 By default, when your component's state or props change, your component will re-render. However, if these change implicitly (eg: data deep within an object changes without changing the object itself) or if your `render()` method depends on some other data, you can tell React that it needs to re-run `render()` by calling `forceUpdate()`.
@@ -94,7 +102,7 @@ If this component has been mounted into the DOM, this returns the corresponding
 bool isMounted()
 ```
 
-`isMounted()` returns true if the component is rendered into the DOM, false otherwise. You can use this method to guard asynchronous calls to `setState()` or `forceUpdate()`.
+`isMounted()` returns `true` if the component is rendered into the DOM, `false` otherwise. You can use this method to guard asynchronous calls to `setState()` or `forceUpdate()`.
 
 > Note:
 >
@@ -104,7 +112,10 @@ bool isMounted()
 ### setProps
 
 ```javascript
-setProps(object nextProps[, function callback])
+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.render()`.
@@ -122,7 +133,10 @@ Calling `setProps()` on a root-level component will change its properties and tr
 ### replaceProps
 
 ```javascript
-replaceProps(object nextProps[, function callback])
+replaceProps(
+  object nextProps,
+  [function callback]
+)
 ```
 
 Like `setProps()` but deletes any pre-existing props instead of merging the two objects.

docs/ref-03-component-specs.md

@@ -129,7 +129,9 @@ If you want to integrate with other JavaScript frameworks, set timers using `set
 ### Updating: componentWillReceiveProps
 
 ```javascript
-componentWillReceiveProps(object nextProps)
+componentWillReceiveProps(
+  object nextProps
+)
 ```
 
 Invoked when a component is receiving new props. This method is not called for the initial render.
@@ -152,7 +154,9 @@ componentWillReceiveProps: function(nextProps) {
 ### Updating: shouldComponentUpdate
 
 ```javascript
-boolean shouldComponentUpdate(object nextProps, object nextState)
+boolean shouldComponentUpdate(
+  object nextProps, object nextState
+)
 ```
 
 Invoked before rendering when new props or state are being received. This method is not called for the initial render or when `forceUpdate` is used.
@@ -166,9 +170,9 @@ shouldComponentUpdate: function(nextProps, nextState) {
 }
 ```
 
-If `shouldComponentUpdate` returns false, then `render()` will be completely skipped until the next state change. (In addition, `componentWillUpdate` and `componentDidUpdate` will not be called.)
+If `shouldComponentUpdate` returns false, then `render()` will be completely skipped until the next state change. In addition, `componentWillUpdate` and `componentDidUpdate` will not be called.
 
-By default, `shouldComponentUpdate` always returns true to prevent subtle bugs when `state` is mutated in place, but if you are careful to always treat `state` as immutable and to read only from `props` and `state` in `render()` then you can override `shouldComponentUpdate` with an implementation that compares the old props and state to their replacements.
+By default, `shouldComponentUpdate` always returns `true` to prevent subtle bugs when `state` is mutated in place, but if you are careful to always treat `state` as immutable and to read only from `props` and `state` in `render()` then you can override `shouldComponentUpdate` with an implementation that compares the old props and state to their replacements.
 
 If performance is a bottleneck, especially with dozens or hundreds of components, use `shouldComponentUpdate` to speed up your app.
 
@@ -176,7 +180,9 @@ If performance is a bottleneck, especially with dozens or hundreds of components
 ### Updating: componentWillUpdate
 
 ```javascript
-componentWillUpdate(object nextProps, object nextState)
+componentWillUpdate(
+  object nextProps, object nextState
+)
 ```
 
 Invoked immediately before rendering when new props or state are being received. This method is not called for the initial render.
@@ -191,7 +197,9 @@ Use this as an opportunity to perform preparation before an update occurs.
 ### Updating: componentDidUpdate
 
 ```javascript
-componentDidUpdate(object prevProps, object prevState)
+componentDidUpdate(
+  object prevProps, object prevState
+)
 ```
 
 Invoked immediately after the component's updates are flushed to the DOM. This method is not called for the initial render.

docs/ref-04-tags-and-attributes.md

@@ -8,7 +8,7 @@ next: events.html
 
 ## Supported Tags
 
-React attempts to support all common elements. If you need an element that isn't listed here, please file an issue.
+React attempts to support all common elements. If you need an element that isn't listed here, please [file an issue](https://github.com/facebook/react/issues/new).
 
 ### HTML Elements
 

docs/ref-09-glossary.md

@@ -44,7 +44,7 @@ var root = <ul className="my-list">
 React.render(root, document.getElementById('example'));
 ```
 
-__Factories__
+### Factories
 
 A `ReactElement`-factory is simply a function that generates a `ReactElement` with a particular `type` property. React has a built-in helper for you to create factories. It's effectively just:
 
@@ -105,7 +105,7 @@ When this constructor is invoked it is expected to return an object with at leas
 var component = new MyComponent(props); // never do this
 ```
 
-Other than for testing, you would normally __never__ call this constructor yourself. React calls it for you.
+Other than for testing, you would normally *never* call this constructor yourself. React calls it for you.
 
 Instead, you pass the `ReactComponent` Class to `createElement` you get a `ReactElement`.
 
@@ -140,13 +140,13 @@ The `render` method of a `ReactComponent` is expected to return another `ReactEl
 
 ## Formal Type Definitions
 
-__Entry Point__
+### Entry Point
 
 ```
 React.render = (ReactElement, HTMLElement | SVGElement) => ReactComponent;
 ```
 
-__Nodes and Elements__
+### Nodes and Elements
 
 ```
 type ReactNode = ReactElement | ReactFragment | ReactText;
@@ -180,7 +180,7 @@ type ReactText = string | number;
 type ReactEmpty = null | undefined | boolean;
 ```
 
-__Classes and Components__
+### Classes and Components
 
 ```
 type ReactClass<TProps> = (TProps) => ReactComponent<TProps>;