#290 closed bug (invalid)
Document behaviour of destructive methods like find etc.
Reported by: | joern | Owned by: | |
---|---|---|---|
Priority: | major | Milestone: | |
Component: | docs | Version: | |
Keywords: | Cc: | ||
Blocked by: | Blocking: |
Description
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...
Change History (2)
comment:1 Changed 16 years ago by
Priority: | critical → major |
---|
comment:2 Changed 16 years ago by
Resolution: | → invalid |
---|---|
Status: | new → closed |
Destructive behaviour will be history from 1.1 on, therefore this ins't necessary anymore.
Note: See
TracTickets for help on using
tickets.
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?
=======================
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.
=======================