Document behaviour of destructive methods like find etc.

[joern]

There have been several requests about the behaviour of find() etc. Most find it unintuitive that these methods are destructive.

I didn't find any documentation about this behaviour in the API or wiki and consider this a bug...

[dave.methvin]

I considered adding a sentence or two to each method to clarify this, but it seems overly redundant and verbose. Earlier I posted a proposal to categorize each method based on its behavior (copied below). Perhaps we could add that category to the method documentation and link to a single page explaining it?

=======================

I think what he's talking about is whether or not it returns what was

just added to the document or the original element. Another example would be whether or not .clone() return the cloned elements in the jQuery set or the original elements. Those sorts of things aren't listed.

Good point, and sometimes I have to pause when using a method I haven't used before. However, I think most jQuery methods fall into just three categories. (I use $ to mean "the elements currently selected by this jQuery object.")

1) Standard methods -- most not listed below Do not change $ and return $ for chaining. If the method creates nodes, they are not part of $. If the method removes nodes that are part of $, the references in $ remain. (That is, they have been removed from the document but are still in $ so you could put them back using a method like appendTo further down the chain.)

2) Filtering methods -- filter, add, not, parents, etc. Push $ on an internal stack and return the (new) filtered $ for chaining. The original $ is available by using .end() in the chain to pop the stack.

3) Set/Get methods -- height, width, css, etc. Called with N arguments (usually none), return the value of the property for the *first* node (element 0) in the jQuery object. Called with N+1 arguments, set the value of the property for each node in $ using the final argument. Return the unchanged $ for chaining.

=======================

[joern]

Destructive behaviour will be history from 1.1 on, therefore this ins't necessary anymore.