[Docs] general improvements

 - Defined 'solo' as a wrapper with one node, and used that terminology throughout.  Removed the term 'current node' as applied to a wrapper, and changed each to better wording.
 - rewrote sections for functions matchesElement, containsMatchingElement, containsAllMatchingElements, containsAnyMatchingElements; each refer to containsMatchIngElement and matchesElement for matching rules.  Renamed the matcher node to 'patternNode' to avoid confusion.
 - compared Shallow and React wrapper methods, corrected a few discrepancies
 - added some notes for methods in React or Shallow that are not in the other
 - added .length to both the React and Shallow directories.

README.md

@@ -6,8 +6,8 @@ Enzyme
 [![npm Version](https://img.shields.io/npm/v/enzyme.svg)](https://www.npmjs.com/package/enzyme) [![License](https://img.shields.io/npm/l/enzyme.svg)](https://www.npmjs.com/package/enzyme) [![Build Status](https://travis-ci.org/airbnb/enzyme.svg)](https://travis-ci.org/airbnb/enzyme) [![Coverage Status](https://coveralls.io/repos/airbnb/enzyme/badge.svg?branch=master&service=github)](https://coveralls.io/github/airbnb/enzyme?branch=master)
 
 
-Enzyme is a JavaScript Testing utility for React that makes it easier to assert, manipulate,
-and traverse your React Components' output.
+Enzyme is a JavaScript Testing utility for React that makes it easier to test your React Components' output.
+You can also manipulate, traverse, and in some ways simulate runtime given the output.
 
 Enzyme's API is meant to be intuitive and flexible by mimicking jQuery's API for DOM manipulation
 and traversal.

docs/api/ReactWrapper/at.md

@@ -26,4 +26,6 @@ expect(wrapper.find(Foo).at(0).props().foo).to.equal('bar');
 
 #### Related Methods
 
-- [`.get(index) => ReactElement`](get.md)
+- [`.get(index) => ReactElement`](get.md) - same, but returns the React node itself, with no wrapper.
+- [`.first() => ReactWrapper`](first.md) - same as at(0)
+- [`.last() => ReactWrapper`](last.md)

docs/api/ReactWrapper/closest.md

@@ -1,9 +1,7 @@
 # `.closest(selector) => ReactWrapper`
 
 Returns a wrapper of the first element that matches the selector by traversing up through the
-current node's ancestors in the tree, starting with itself.
-
-Note: can only be called on a wrapper of a single node.
+wrapped node's ancestors in the tree, starting with itself. It must be a single-node wrapper.
 
 
 #### Returns

docs/api/ReactWrapper/containsAllMatchingElements.md

@@ -1,23 +1,20 @@
-# `.containsAllMatchingElements(nodes) => Boolean`
+# `.containsAllMatchingElements(patternNodes) => Boolean`
 
-Returns whether or not one of the given react elements are all matching one element in the render tree.
-It will determine if an element in the wrapper __looks like__ one of the expected element by checking if all props of the expected element are present on the wrappers element and equals to each other.
+Returns whether or not all of the given react elements in `patternNodes` match an element in the wrapper's render tree. Every single element of `patternNodes` must be matched one or more times. Matching follows the rules for `containsMatchingElement`.
 
 
 #### Arguments
 
-1. `nodes` (`Array<ReactElement>`): The array of nodes whose presence you are detecting in the current instance's
+1. `patternNodes` (`Array<ReactElement>`): The array of nodes whose presence you are detecting in the current instance's
 render tree.
 
 
-
 #### Returns
 
 `Boolean`: whether or not the current wrapper has nodes anywhere in its render tree that looks
 like the nodes passed in.
 
 
-
 #### Example
 
 
@@ -44,3 +41,10 @@ expect(wrapper.containsAllMatchingElements([
 when you are calling it you are calling it with an array of ReactElement or a JSX expression.
 - Keep in mind that this method determines matching based on the matching of the node's children as
 well.
+
+
+#### Related Methods
+
+- [`.matchesElement() => ReactWrapper`](matchesElement.md) - rules for matching each node
+- [`.containsMatchingElement() => ReactWrapper`](containsMatchingElement.md) - rules for matching whole wrapper
+- [`.containsAnyMatchingElements() => ReactWrapper`](containsAnyMatchingElements.md) - must match at least one in patternNodes

docs/api/ReactWrapper/containsAnyMatchingElements.md

@@ -1,23 +1,20 @@
-# `.containsAnyMatchingElements(nodes) => Boolean`
+# `.containsAnyMatchingElements(patternNodes) => Boolean`
 
-Returns whether or not one of the given react elements is matching on element in the render tree.
-It will determine if an element in the wrapper __looks like__ one of the expected element by checking if all props of the expected element are present on the wrappers element and equals to each other.
+Returns whether or not at least one of the given react elements in `patternNodes` matches an element in the wrapper's render tree. One or more elements of `patternNodes` must be matched one or more times. Matching follows the rules for `containsMatchingElement`.
 
 
 #### Arguments
 
-1. `nodes` (`Array<ReactElement>`): The array of nodes whose presence you are detecting in the current instance's
+1. `patternNodes` (`Array<ReactElement>`): The array of nodes whose presence you are detecting in the current instance's
 render tree.
 
 
-
 #### Returns
 
 `Boolean`: whether or not the current wrapper has a node anywhere in its render tree that looks
 like one of the array passed in.
 
 
-
 #### Example
 
 
@@ -44,3 +41,10 @@ expect(wrapper.containsAnyMatchingElements([
 when you are calling it you are calling it with an array ReactElement or a JSX expression.
 - Keep in mind that this method determines equality based on the equality of the node's children as
 well.
+
+
+#### Related Methods
+
+- [`.matchesElement() => ReactWrapper`](matchesElement.md) - rules for matching each node
+- [`.containsMatchingElement() => ReactWrapper`](containsMatchingElement.md) - rules for matching whole wrapper
+- [`.containsAllMatchingElements() => ReactWrapper`](containsAllMatchingElements.md) - must match all nodes in patternNodes

docs/api/ReactWrapper/containsMatchingElement.md

@@ -1,16 +1,18 @@
-# `.containsMatchingElement(node) => Boolean`
+# `.containsMatchingElement(patternNode) => Boolean`
 
-Returns whether or not a given react element matches one element in the render tree.
-It will determine if an element in the wrapper matches the expected element by checking if all props of the expected element are present on the wrapper's element and equals to each other.
+Returns whether or not a `patternNode` react element matches any element in the render tree.
+* the matches can happen anywhere in the wrapper's contents
+* the wrapper can contain more than one node; all are searched
+
+Otherwise, the match follows the same rules as `matchesElement`.
 
 
 #### Arguments
 
-1. `node` (`ReactElement`): The node whose presence you are detecting in the current instance's
+1. `patternNode` (`ReactElement`): The node whose presence you are detecting in the current instance's
 render tree.
 
 
-
 #### Returns
 
 `Boolean`: whether or not the current wrapper has a node anywhere in its render tree that matches
@@ -42,3 +44,9 @@ expect(wrapper.containsMatchingElement(<div data-foo="foo" data-bar="bar" />)).t
 when you are calling it you are calling it with a ReactElement or a JSX expression.
 - Keep in mind that this method determines equality based on the equality of the node's children as
 well.
+
+
+#### Related Methods
+
+- [`.containsAllMatchingElements() => ReactWrapper`](containsAllMatchingElements.md) - must match all nodes in patternNodes
+- [`.containsAnyMatchingElements() => ReactWrapper`](containsAnyMatchingElements.md) - must match at least one in patternNodes

docs/api/ReactWrapper/detach.md

@@ -9,7 +9,7 @@ The method is intentionally not "fluent" (in that it doesn't return `this`) beca
 not be doing anything with this wrapper after this method is called.
 
 Using `attachTo`/`hydrateIn` is not generally recommended unless it is absolutely necessary to test
-something.  It is your responsibility to clean up after yourself at the end of the test if you do
+something. It is your responsibility to clean up after yourself at the end of the test if you do
 decide to use it, though.
 
 

docs/api/ReactWrapper/exists.md

@@ -1,6 +1,6 @@
 # `.exists([selector]) => Boolean`
 
-Returns whether or not the current node exists. Or, if a selector is passed in, whether that selector has any matching results.
+Returns whether or not any nodes exist in the wrapper. Or, if a selector is passed in, whether that selector has any matches in the wrapper.
 
 
 
@@ -12,7 +12,7 @@ Returns whether or not the current node exists. Or, if a selector is passed in,
 
 #### Returns
 
-`Boolean`: whether or not the current node exists, or the selector had any results.
+`Boolean`: whether or not any nodes are on the list, or the selector had any matches.
 
 
 

docs/api/ReactWrapper/first.md

@@ -1,18 +1,22 @@
 # `.first() => ReactWrapper`
 
-Reduce the set of matched nodes to the first in the set.
-
+Reduce the set of matched nodes to the first in the set, just like `.at(0)`.
 
 
 #### Returns
 
 `ReactWrapper`: A new wrapper that wraps the first node in the set.
 
 
-
 #### Examples
 
 ```jsx
 const wrapper = mount(<MyComponent />);
 expect(wrapper.find(Foo).first().props().foo).to.equal('bar');
 ```
+
+
+#### Related Methods
+
+- [`.at(index) => ReactWrapper`](at.md) - retrieve any wrapper node
+- [`.last() => ReactWrapper`](last.md)

docs/api/ReactWrapper/get.md

@@ -8,13 +8,11 @@ Returns the node at a given index of the current wrapper.
 1. `index` (`Number`): A zero-based integer indicating which node to retrieve.
 
 
-
 #### Returns
 
 `ReactElement`: The retrieved node.
 
 
-
 #### Examples
 
 ```jsx
@@ -23,7 +21,6 @@ expect(wrapper.find(Foo).get(0).props.foo).to.equal('bar');
 ```
 
 
-
 #### Related Methods
 
-- [`.at(index) => ReactWrapper`](at.md)
+- [`.at(index) => ReactWrapper`](at.md) - same, but returns the React node in a single-node wrapper.

docs/api/ReactWrapper/hasClass.md

@@ -1,18 +1,16 @@
 # `.hasClass(className) => Boolean`
 
-Returns whether or not the current node has a `className` prop including the passed in class name.
+Returns whether or not the wrapped node has a `className` prop including the passed in class name. It must be a single-node wrapper.
 
 
 #### Arguments
 
 1. `className` (`String`): A single class name.
 
 
-
 #### Returns
 
-`Boolean`: whether or not the current node has the class.
-
+`Boolean`: whether or not the wrapped node has the class.
 
 
 #### Example

docs/api/ReactWrapper/hostNodes.md

@@ -1,18 +1,25 @@
 # `.hostNodes() => ReactWrapper`
 
 Returns a new wrapper with only host nodes.
-
+When using `react-dom`, host nodes are HTML elements rather than custom React components, e.g. `<div>` versus `<MyComponent>`.
 
 
 #### Returns
 
 `ReactWrapper`: A new wrapper that wraps the filtered nodes.
 
 
-
 #### Examples
 
+The following code takes a wrapper with two nodes, one a `<MyComponent>` React component, and the other a `<span>`, and filters out the React component.
+
 ```jsx
-const wrapper = mount(<div><MyComponent className="foo" /><div className="foo" /></div>);
-expect(wrapper.find('.foo').hostNodes()).to.have.lengthOf(1);
+const wrapper = mount((
+  <div>
+    <MyComponent className="foo" />
+    <span className="foo" />
+  </div>
+));
+const twoNodes = wrapper.find('.foo');
+expect(twoNodes.hostNodes()).to.have.lengthOf(1);
 ```

docs/api/ReactWrapper/instance.md

@@ -1,19 +1,60 @@
 # `.instance() => ReactComponent`
 
-Returns the wrapper's underlying instance.
+Returns the single-node wrapper's node's underlying class instance; `this` in its methods. It must be a single-node wrapper.
 
+NOTE: With React `16` and above, `instance()` returns `null` for stateless functional components.
 
 
 #### Returns
 
 `ReactComponent|DOMComponent`: The retrieved instance.
 
 
-
 #### Example
 
+<!-- eslint react/prop-types: 0, react/prefer-stateless-function: 0 -->
+```jsx
+function Stateless() {
+  return <div>Stateless</div>;
+}
+
+class Stateful extends React.Component {
+  render() {
+    return <div>Stateful</div>;
+  }
+}
+```
+
+#### React 16.x
 ```jsx
-const wrapper = mount(<MyComponent />);
-const inst = wrapper.instance();
-expect(inst).to.be.instanceOf(MyComponent);
+test('shallow wrapper instance should be null', () => {
+  const wrapper = mount(<Stateless />);
+  const instance = wrapper.instance();
+
+  expect(instance).to.equal(null);
+});
+
+test('shallow wrapper instance should not be null', () => {
+  const wrapper = mount(<Stateful />);
+  const instance = wrapper.instance();
+
+  expect(instance).to.be.instanceOf(Stateful);
+});
+```
+
+#### React 15.x
+```jsx
+test('shallow wrapper instance should not be null', () => {
+  const wrapper = mount(<Stateless />);
+  const instance = wrapper.instance();
+
+  expect(instance).to.be.instanceOf(Stateless);
+});
+
+test('shallow wrapper instance should not be null', () => {
+  const wrapper = mount(<Stateful />);
+  const instance = wrapper.instance();
+
+  expect(instance).to.be.instanceOf(Stateful);
+});
 ```

docs/api/ReactWrapper/is.md

@@ -1,18 +1,16 @@
 # `.is(selector) => Boolean`
 
-Returns whether or not the current node matches a provided selector.
+Returns whether or not the single wrapped node matches the provided selector. It must be a single-node wrapper.
 
 
 #### Arguments
 
 1. `selector` ([`EnzymeSelector`](../selector.md)): The selector to match.
 
 
-
 #### Returns
 
-`Boolean`: whether or not the current node matches a provided selector.
-
+`Boolean`: whether or not the wrapped node matches the provided selector.
 
 
 #### Example
@@ -22,4 +20,3 @@ Returns whether or not the current node matches a provided selector.
 const wrapper = mount(<div className="some-class other-class" />);
 expect(wrapper.is('.some-class')).to.equal(true);
 ```
-

docs/api/ReactWrapper/isEmpty.md

@@ -1,13 +1,12 @@
 # `.isEmpty() => Boolean`
 **Deprecated**: Use [.exists()](exists.md) instead.
 
-Returns whether or not the current node is empty.
+Returns whether or not the wrapper is empty.
 
 
 #### Returns
 
-`Boolean`: whether or not the current node is empty.
-
+`Boolean`: whether or not the wrapper is empty.
 
 
 #### Example

docs/api/ReactWrapper/isEmptyRender.md

@@ -1,6 +1,6 @@
 # `.isEmptyRender() => Boolean`
 
-Returns whether or not the current component returns one of the allowed falsy values: `false` or `null`.
+Returns whether or not the wrapper would ultimately render only the allowed falsy values: `false` or `null`.
 
 #### Returns
 

docs/api/ReactWrapper/key.md

@@ -1,8 +1,6 @@
 # `.key() => String`
 
-Returns the key value for the node of the current wrapper.
-
-NOTE: can only be called on a wrapper of a single node.
+Returns the key value for the node of the current wrapper. It must be a single-node wrapper.
 
 #### Example