Improve readme documentation

Author: Rishabh Rao

README.md

@@ -1,9 +1,16 @@
-# react-error-boundary
+react-error-boundary
+====================
 
-Sample reusable React error boundary component for React 16+
+**A simple, reusable React error boundary component for React 16+.**
 
-The simplest way to use a boundary is to wrap it around any component that may throw an error.
-This will handle errors thrown by that component's descendants also.
+React [v16](https://reactjs.org/blog/2017/09/26/react-v16.0.html) introduced the concept of [“error boundaries”](https://reactjs.org/docs/error-boundaries.html).
+
+This component provides a simple and reusable wrapper that you can use to wrap around your components. Any rendering errors in your components hierarchy can then be gracefully handled.
+
+# Usage
+
+The simplest way to use `<ErrorBoundary>` is to wrap it around any component that may throw an error.
+This will handle errors thrown by that component and its descendants too.
 
 ```jsx
 import ErrorBoundary from 'react-error-boundary';
@@ -13,40 +20,53 @@ import ErrorBoundary from 'react-error-boundary';
 </ErrorBoundary>
 ```
 
-You can react to errors (eg for logging) by providing an `onError` callback:
+You can react to errors (e.g. for logging) by providing an `onError` callback:
 
 ```jsx
 import ErrorBoundary from 'react-error-boundary';
 
 const myErrorHandler = (error: Error, componentStack: string) => {
-  // ...
+  // Do something with the error
+  // E.g. log to an error logging client here
 };
 
 <ErrorBoundary onError={myErrorHandler}>
   <ComponentThatMayError />
 </ErrorBoundary>
 ```
 
-You can also customize the fallback appearance:
+You can also customize the fallback component’s appearance:
 
 ```jsx
+import { ErrorBoundary } from 'react-error-boundary';
+
 const MyFallbackComponent = ({ componentStack, error }) => (
-  <div/>
-)
+  <div>
+    <p><strong>Oops! An error occured!</strong></p>
+    <p>Here’s what we know…</p>
+    <p><strong>Error:</strong> {error.toString()}</p>
+    <p><strong>Stacktrace:</strong> {componentStack}</p>
+  </div>
+);
 
 <ErrorBoundary FallbackComponent={MyFallbackComponent}>
   <ComponentThatMayError />
 </ErrorBoundary>
 ```
 
-You can also use it as a HOC:
+You can also use it as a [higher-order component](https://reactjs.org/docs/higher-order-components.html):
 
 ```jsx
-import {withErrorBoundary} from 'react-error-boundary';
+import { ErrorBoundaryFallbackComponent, withErrorBoundary } from 'react-error-boundary';
 
 const ComponentWithErrorBoundary = withErrorBoundary(
-  ComponentToDecorate: Element<any>,
-  CustomFallbackComponent: ?Element<any>,
-  onErrorHandler: ?(error: Error, componentStack: string) => void,
+  ComponentThatMayError,
+  ErrorBoundaryFallbackComponent, // Or pass in your own fallback component
+  onErrorHandler: (error, componentStack) => {
+    // Do something with the error
+    // E.g. log to an error logging client here
+  },
 );
-```
+
+<ComponentWithErrorBoundary />
+```