Merge pull request #580 from kevinzwh/correct-props-docs

[Docs] Add documentation note clarifying shallow wrapper prop functions

docs/api/ShallowWrapper/prop.md

@@ -1,22 +1,45 @@
 # `.prop(key) => Any`
 
-Returns the prop value for the node of the current wrapper with the provided key.
+Returns the prop value for the root node of the wrapper with the provided key.
+`.prop(key)` can only be called on a wrapper of a single node.
 
-NOTE: can only be called on a wrapper of a single node.
+NOTE: When called on a shallow wrapper, `.prop(key)` will return values for
+props on the root node that the component *renders*, not the component itself.
+To return the props for the entire React component, use `wrapper.instance().props`.
+See [`.instance() => ReactComponent`](instance.md)
 
 #### Arguments
 
 1. `key` (`String`): The prop name such that this will return value will be the `this.props[key]`
-of the component instance.
+of the root node of the component.
 
 
 
 #### Example
 
 
 ```jsx
-const wrapper = shallow(<MyComponent foo={10} />);
-expect(wrapper.prop('foo')).to.equal(10);
+const MyComponent = React.createClass({
+  render() {
+    return (
+        <div className="foo bar" includedProp={this.props.includedProp}>Hello</div>
+    )
+  }
+})
+const wrapper = shallow(<MyComponent includedProp="Success!" excludedProp="I'm not included" />);
+expect(wrapper.prop('includedProp')).to.equal("Success!");
+
+// Warning: .prop(key) only returns values for props that exist in the root node.
+// See the note above about wrapper.instance().props to return all props in the React component.
+
+wrapper.prop('includedProp');
+// "Success!"
+
+wrapper.prop('excludedProp');
+// undefined
+
+wrapper.instance().props.excludedProp;
+// "I'm not included"
 ```
 
 

docs/api/ShallowWrapper/props.md

@@ -1,16 +1,38 @@
 # `.props() => Object`
 
-Returns the props hash for the current node of the wrapper.
+Returns the props hash for the root node of the wrapper. `.props()` can only be
+called on a wrapper of a single node.
 
-NOTE: can only be called on a wrapper of a single node.
+NOTE: When called on a shallow wrapper, `.props()` will return values for
+props on the root node that the component *renders*, not the component itself.
+To return the props for the entire React component, use `wrapper.instance().props`.
+See [`.instance() => ReactComponent`](instance.md)
 
 
 #### Example
 
 
 ```jsx
-const wrapper = shallow(<MyComponent foo={10} />);
-expect(wrapper.props().foo).to.equal(10);
+const MyComponent = React.createClass({
+  render() {
+    return (
+        <div className="foo bar" includedProp={this.props.includedProp}>Hello</div>
+    )
+  }
+})
+const wrapper = shallow(<MyComponent includedProp="Success!" excludedProp="I'm not included" />);
+expect(wrapper.props().includedProp).to.equal("Success!");
+
+// Warning: .props() only returns props that are passed to the root node,
+// which does not include excludedProp in this example.
+// See the note above about wrapper.instance().props.
+
+wrapper.props();
+// {children: "Hello", className: "foo bar", includedProp="Success!"}
+
+wrapper.instance().props;
+// {children: "Hello", className: "foo bar", includedProp:"Success!", excludedProp: "I'm not included"}
+
 ```