The selectors level 2 spec is rather hard to follow around the behaviour of the refNodes parameter. In loose terms, it seems as if the instruction "the implementation must process this argument according to the steps for determining reference nodes" and the linked algorithm are supposed to set a global variable that is lated accessed to determine the nodes that match :reference in the matcher. It would be nice (especially for the first-time reader) if this implicit behaviour was made explicit. One way to do this would be to use some sort of pseudo-code instead of prose e.g.

1. let /reference_nodes/ be the result of calling the algorithm for determining reference nodes with parameter /refNodes/

2. Let /final_selector/ be the result of calling the algoritm for processing selectors with parameter /selectors/

3. If /selectors/ is a selector string or a scoped selector string, return the first Element node matching /final_selector/ with contextual reference nodes /reference_nodes/ that lies within the subtrees of the context node

Otherwise if...


And so on. Obviously there are other approaches that would work. However the general idea is to make it explicit how the function arguments are used to affect the nodes returned.