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.
=
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?
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.