Clarify .prev

[jcuenod]

I the .prev docs the description is

Get the immediately preceding sibling of each element in the set of matched elements,
optionally filtered by a selector.

I took this to mean that, given a selector, .prev would traverse back through sibling elements until it found one matching that selector. See also http://stackoverflow.com/questions/5452917/jquery-prevselector-not-working.

In the .next docs, however, it is far more clear:

... it retrieves the next sibling only if it matches that selector.

[dmethvin]

Good clarification. Also applies to .next(), .prevAll(), and .nextAll(), and a lot of the other traversing methods so perhaps it's worth having a notes.xsl entry that explains it?

[AurelioDeRosa]

Definitely worth a note. @jcuenod would you like to submit a PR?

[jcuenod]

Regarding the notes entry, I'm happy to do it if people agree but if it's only .next and .prev it may not be necessary. Are there other methods that need it?

@dmethvin I think when it comes to .prevAll and .nextAll things are a bit different. The explanation could say something to the effect that siblings are filtered according to the pattern and if none match an empty collection is returned. In the case of .next and .prev though, it could be (wrongly) understood that the functions are implicitly recursive and iterate until they find a match or run out of siblings.

[dmethvin]

@jcuenod I see your point. The main confusion seems to be with .prev and .next so creating a reusable text for a short sentence may not pay off. @AurelioDeRosa would you be okay with just modifying those two?

[AurelioDeRosa]

I'll take a look at this tonight @dmethvin. Thank you for the ping.