mutuallyExclusiveProps is unintuitive / poorly documented

[pillowfication]

mutuallyExclusiveProps() only checks that at least one exclusive prop is provided. Otherwise it throws with at least one prop that is mutually exclusive with this propType is required. However, two exclusive props are required for mutuallyExclusiveProps() to do anything, since the current propName is not considered an exclusive prop.

// All equivalent
foo: mutuallyExclusiveProps(validator, 'foo')
foo: mutuallyExclusiveProps(validator, 'bar')
foo: mutuallyExclusiveProps(validator, 'foo').isRequired
foo: mutuallyExclusiveProps(validator, 'bar').isRequired
foo: validator

The behavior of mutuallyExclusiveProps().isRequired is unclear. The only requirement is that

it('fails when required, and one of the exclusive props is null/undefined')

and this doesn't describe the current behavior of .isRequired. Currently, if the current propName is not listed as an exclusive prop, then mutuallyExclusiveProps() behaves the exact same as mutuallyExclusiveProps().isRequired. If the current propName is included as an exclusive prop, then the only difference is that propName={null/undefined} is additionally considered as a set prop.

This seems strange because of the following scenario:

Component.propTypes = {
  foo: mutuallyExclusiveProps(any, 'foo', 'bar').isRequired
}

<Component bar /> // passes
<Component foo={null} bar /> // fails
<Component foo={undefined} bar /> // fails