Ambiguous/misleading/incorrect documentation regarding PropTypes.node.

[MrJoy]

  // Anything that can be rendered: numbers, strings, elements or an array
  // (or fragment) containing these types.
  optionalNode: PropTypes.node,

  // A React element.
  optionalElement: PropTypes.element,

Upon reading this, I -- and a member of my team -- came away with the understanding that PropTypes.node was suitable for things such as DOM nodes/elements (e.g. event.currentTarget). After poring over the code here, it appears that this is not the case and that the only type of "node" that's allowed is a React node.

I'd recommend at least updating the wording on this. Perhaps something of the form:

  // A single React element.
  optionalElement: PropTypes.element,

  // Anything that can be rendered, excluding raw DOM elements: numbers, strings, React elements or an array/fragment thereof.
  optionalNode: PropTypes.node,

[ljharb]

a raw DOM element isn't something that can be rendered, so there's no need to exclude it from the definition "anything that can be rendered"

[MrJoy]

"You're technically correct! The best kind of correct!"

Your mental model of what "can be rendered" may be entirely accurate in context of React specifically, but using that for documentation without being mindful of how other folks less steeped in React might perceive things is just creating landmines for people -- as my teammate and I discovered the hard way.

Both I, and my teammate were misled by this because our mental model of what "can be rendered" absolutely includes DOM elements. DOM elements are a thing the browser renders.

The typical reader of the documentation for those project will most likely not have read either the documentation to React end-to-end, or the code for React itself. They will most likely not have the same mental model as you do.

Documentation isn't useful unless it's written for the reader.

In this case, the only way I was able to correct my understanding was to read through the code for this project. While that's always worth doing, frankly I would be happier if there had been no documentation at all because I would have spent less total time sorting things out.

I'd ask that instead of just dismissing this concern out of hand you consider that this is a rare opportunity to make your product more valuable by just... changing a few words. No complex engineering. No regression testing. Just shuffling a few words around. How awesome is that?

[ljharb]

What about "Anything that can be rendered by React: numbers, strings, elements or an array (or fragment) containing these types." (since the list is exhaustive)

[MrJoy]

That doesn't really address the source of confusion here: "Element" remains ambiguous from the perspective of an outsider. Is there a particular page of React docs that talks about what is "renderable"? If so, perhaps you could link to that to allow people to fill out their understanding without duplication of effort?

[ljharb]

https://reactjs.org/docs/rendering-elements.html ?

[MrJoy]

That's certainly an improvement, I think.