Specify that .data and .attr can't be mixed

[cosmo0]

I found out the hard way that you can't mix usage of .data and .attr.

The .data documentation clearly states that it doesn't change the DOM upon setting a value.

However, the .attr documentation talks at length about the difference between it and prop, but does not state that it doesn't change the dataset of the DOM node, as demonstrated here: https://codepen.io/cosmo0/pen/YzKVBPp?editors=0011

So your code has to be very strict about using either .data or .attr, because mixing both can result in unexpected behavior, at least when you don't know how jQuery works.

I understand it's by-design, but maybe a warning in the .attr documentation (and/or the .data?) would help people to not fall for this trap?

[mgol]

This behavior is documented at https://api.jquery.com/data/#data-html5. Is there something missing?

[cosmo0]

Yes, if I carefully read the documentation of data then think about it for a while, I can deduce why my code doesn't work (which I did).

However, is the documentation destined to be helpful to new developers too? (legit quesiton)
If it is, then a warning in the attr documentation would help a lot. Something like a small warning: "because of the way .data works, if you set a new value to data-foo using .attr, it won't be retrievable using .data(foo)".

[mgol]

That's a tricky question! We strive for the docs to be as helpful to newcomers as possible. That said, newcomers often have simple problems listing each of which would increase the size of the API docs so much that it'd stop being readable, including to these newcomers. So it's always a tradeoff.

That said, I can see how the note here may not be prominent enough to be noticeable. If you have a specific suggestion on how to integrate that into the existing API page, we accept pull requests, I'd be happy to review one.