pending → closed
it must do more to prevent ambiguity
This must not be very ambiguous to most people, we don't get a lot of confusion about it. That's why I think docs may be the best path.
what should developers use instead to deal with trees containing text nodes?
The tree itself will contain text nodes, obviously. The question is whether the jQuery collection of nodes should contain text nodes. Generally it doesn't unless you try hard with methods like
It isn't like we made up these rules out of thin air; CSS selectors only target elements and not text nodes. Google will find plenty of solutions for handling these cases including plugins, but you could write a new one if the existing solutions aren't satisfactory.