Skip to main content

Bug Tracker

Side navigation

#290 closed bug (invalid)

Opened October 19, 2006 07:36PM UTC

Closed November 17, 2006 03:14PM UTC

Last modified June 20, 2007 01:28AM UTC

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

Attachments (0)
Change History (2)

Changed October 20, 2006 03:53PM UTC by dave.methvin comment:1

priority: criticalmajor

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.

=

Changed November 17, 2006 03:14PM UTC by joern comment:2

resolution: → invalid
status: newclosed

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