From 9d9ec7cc8aa95681e89245e63847cdec6a3161e7 Mon Sep 17 00:00:00 2001 From: Andreas Savvides Date: Mon, 14 Sep 2015 18:23:00 +0100 Subject: [PATCH 1/4] Make "Component API" more readable --- docs/ref-02-component-api.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/ref-02-component-api.md b/docs/ref-02-component-api.md index aaf04c7d..a2f08ddf 100644 --- a/docs/ref-02-component-api.md +++ b/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. From c56d0fd84f520769da37d5f286f8f0d4fe6db0ae Mon Sep 17 00:00:00 2001 From: Andreas Savvides Date: Mon, 14 Sep 2015 18:43:16 +0100 Subject: [PATCH 2/4] Make "Component Specs and Lifecycle" more readable --- docs/ref-03-component-specs.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/ref-03-component-specs.md b/docs/ref-03-component-specs.md index d9c2e86f..3de92fdf 100644 --- a/docs/ref-03-component-specs.md +++ b/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. From fc5364ba84ce240db0f6fb8efd154a9145f99058 Mon Sep 17 00:00:00 2001 From: Andreas Savvides Date: Mon, 14 Sep 2015 18:45:29 +0100 Subject: [PATCH 3/4] Make it easier to create an issue --- docs/ref-04-tags-and-attributes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ref-04-tags-and-attributes.md b/docs/ref-04-tags-and-attributes.md index 8992d990..488c5db0 100644 --- a/docs/ref-04-tags-and-attributes.md +++ b/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 From d93d35887bd674b1a437fb2cc1d8a6242866f8c1 Mon Sep 17 00:00:00 2001 From: Andreas Savvides Date: Mon, 14 Sep 2015 18:55:34 +0100 Subject: [PATCH 4/4] Use same type of markdown as everywhere else for Glossary --- docs/ref-09-glossary.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/ref-09-glossary.md b/docs/ref-09-glossary.md index 3179cc1f..5c0e460d 100644 --- a/docs/ref-09-glossary.md +++ b/docs/ref-09-glossary.md @@ -44,7 +44,7 @@ var root =
    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) => ReactComponent;