The current state of the docs implies that

var arr = $(selector).map(callback)

will not work, since no version is documented as having the callback in the first parameter. But it does seem to.

But it also implies that

$.map($(selector), callback) 

will work, whereas it always seems to return an empty array, from my brief trials.

We don't currently document the parameters for functions that are received as input to higher-order functions, like jQuery.ajax's complete callback.

The documentation for .queue([queueName], callback) does not mention that the queued function is executed once for every individual element within a jQuery set (as opposed to running once for the whole set). There also don't appear to be any examples for that method signature that show it being used on jQuery sets of multiple elements.

Either an explicit mention, or an example that shows $(...).queue(callback) being used on a set of multiple elements, should be enough to clarify the ambiguity imo.

Now that .always(), .done() and .fail() are the preferred methods for implementing callbacks from a jQuery.ajax() invocation, and the old methods have been deprecated, it might be a good time to explain the arguments accessible by each of the new methods, and additionally the .then() and .pipe() when applied to jQuery.ajax() invocations?

When browsing the jQuery documentation on api.jquery.com, the available arguments are not listed anywhere, nor are they immediately obvious from elsewhere on the site.

Please would you consider improving the jQuery documentation - for the benefit of other developers who, like myself, cannot see how things work without delving into a debug session? Perhaps you could include the methods clearly within the listing of jQuery.ajax(), noting that the methods are implementations of Deferred and included here for clarity only?

Perhaps you could add a brief section immediately beneath the main properties/functions listing of jQuery.ajax(), showing definitively what arguments are available to each method's callbacks. I am guessing that the arguments are thus, and perhaps this is how they could be shown (once you have confirmed that my guesses are correct!)?:-

_Methods_ (part of jqXHR and Deferred implementations, shown here for clarity only)

.ajax().always(function(a, textStatus, b){});
Replaces method .complete() which was deprecated in jQuery 1.8.
In response to successful transaction, arguments are same as .done() (ie. a = data, b = jqXHR) and for failed transactions the arguments are same as .fail() (ie. a = jqXHR, b = errorThrown).
This is an alternative construct for the complete callback function above. Refer to deferred.always() for implementation details.

.ajax().done(function(data, textStatus, jqXHR){});
Replaces method .success() which was deprecated in jQuery 1.8.
This is an alternative construct for the success callback function above. Refer to deferred.done() for implementation details.

.ajax().fail(function(jqXHR, textStatus, errorThrown){});
Replaces method .error() which was deprecated in jQuery 1.8.
This is an alternative construct for the complete callback function above. Refer to deferred.fail() for implementation details.

.ajax().then(function(data, textStatus, jqXHR){}, function(jqXHR, textStatus, errorThrown){});
Incorporates the functionality of .done() and .fail() methods.
Refer to deferred.then() for implementation details.

.ajax().pipe(function(data, textStatus, jqXHR){}, function(jqXHR, textStatus, errorThrown){});
Incorporates the functionality of .done() and .fail() methods, allowing the underlying Promise to be manipulated.
Refer to deferred.pipe() for implementation details.

My guesswork may be incorrect? This perhaps illustrates the need to improve the documentation within jQuery.ajax().

Hope you can do something to improve documentation.

Kind regards,
Alan
(edited to note that .complete(), .error() and .success() have already been deprecated, and to explain the use of .then() and .pipe() with .ajax())

Where I came across it was at http://jqueryui.com/demos/accordion/#option-animated

Take for instance the second property in the Options tab, "actve". It says you can use "Selector, Element, jQuery, Boolean, Number" and each one of those is a link. If you click "Selector" you get a popup that contains a link to the Selectors API page but instead of that page (http://api.jquery.com/category/selectors/) it points to http://jqueryui.com/Selectors which is a 404.

That is all.

It appears that if you set a queue name (string) the animation does not run immediately. I found you had to call dequeue. Since this wasn't in the docs it took a bit to figure it out.

It would help if the documentation either specified the need to dequeue or perhaps this is a bug?

Setting "queue" to true triggers the animation immediately if there is currently nothing in the q.

Example:
Nada: $('html,body').animate({scrollTop:200},{queue:'scr',duration:1000});
Woohoo: $('html,body').animate({scrollTop:200},{queue:'scr',duration:1000}).dequeue('scr');

check with @jaubourg before updating

• mention that cache: false works only with HEAD and GET requests,
• mention that it does so by adding/replacing a "_={timestamp}" to the get parameters
• the param is NOT needed for other requests except in IE8 when you POST to a URL that you already requested with a GET

http://api.jquery.com/parent-selector/

Please add ElMoonLite's comment into the doc:

if you are looking for the direct parent(s) of the item(s) in current selection:
use $("someselection").parent().dostuff

if you are looking for all ancestors of the item(s) in current selection:
use $("someselection").parents().dostuff"

The documentation currently does not mention the existence of parents() at all.
noobs who don't read the comments might miss it. :)

.fadeOut( [duration] [, callback] ) does not work in 1.2.6 but .fadeOut( [duration] [, easing] [, callback] ) does.

According to the documentation, the $.fn.html() function only takes a string or a function. However, after examining the source, it internally calls .empty().append(value) and therefore does support (and should state that it supports) all of the same signatures that append() supports.

Are there plans to change how this works?

The internet groans and creaks under the weight of all the unnecessary .each methods out there. Something like this at the top of the .each docs

NOTE: Most built-in JQuery methods are applied to every element in a selector match. If you don't need to deal with elements on a case by case by case basis and just want to perform the same action on each one, you don't need to use the .each method.

jqXHR.status could be better documented here: http://api.jquery.com/jQuery.ajax/#jqXHR .
Also the possible values for thrownError should be documented here: http://api.jquery.com/ajaxError/

I had some problems to figure out, how to distinguish between an aborted and a failed request in jQuery.ajaxError() due to missing documentation. See the related discussion here:

jquery/jquery-ui@0d0c862#commitcomment-1244608

I started up draft docs over on https://gist.github.com/54829d408993526fe475

We need to get these new methods and options documented.

The docs at this location: http://api.jquery.com/jquery-2/

Has this demo code:
var a = { what: "A regular JS object" },
b = $('body');

if ( a.jquery ) { // falsy, since it's undefined
alert(' a is a jQuery object! ');
}

if ( b.jquery ) { // truthy, since it's a string
alert(' b is a jQuery object! ');
}

Shouldn't the first alert be "a is NOT a jQuery object"?

It seems not to be possible to hit this converter:

$.ajaxSetup({
    converters: {
        "mycustomtype json": function (result) {
            //do stuff
            return newresult;
        }
    }
});

This should be called if the response has Content-Type 'mycustomtype' and the caller expects json.

Ticket: http://bugs.jquery.com/ticket/11376

Team notes

I've already written up the docs for this here: https://github.com/addyosmani/api.jquery.com/blob/11376/entries/jQuery.ajax.xml. Will make a pull request soon.

I don't think the descendant selector docs at http://api.jquery.com/descendant-selector/ explain that you can have more than two selectors in your query.

i.e. $('div#foo ul#bar li a') vs just the two in the example given, $("form input")

The site currently generates all top-level categories with no custom category slugs or descriptions or child categories.

Fix: generate a dist/taxonomies.xml from category xml files to support category descriptions and sub-categories.

In the jQuery.ajax docs, the error handler mentions: Note: This handler is not called for cross-domain script and JSONP requests

It is being called for same-domain JSONP requests.

The description of the :parent selector reads: Select all elements that are the parent of another element, including text nodes.

http://api.jquery.com/parent-selector/

Suppose you have: <div> <p id="secret">jQuery is evil!</p> </div>

It is not clear what jQuery("p:parent") matches. Does it match the div, i.e. the paragraph's parent? Or does it match the paragraph?

The answer is that :parent matches the paragraph. This can be deducted from observation of other selector constructs and the realization that a selector doing the former would be :parent(p), but this is far from obvious. It is not clear that :parent means "is a parent", but not "the parent of". Some have even suggested to rename the selector in the documentation comments. I don't know if this is desirable, but kk and Jakub Konecki suggested :hasChild" and :isParent. I did find it very surprising to read that :parent's opposite was :empty.

Furthermore, the current description implies that text nodes are elements, which is misleading.

A description which would fix both issues would be: Select all elements that have a child node (either an element or text).

Ticket: http://bugs.jquery.com/ticket/11253

The noConflict documentation says...

If we need to use another JavaScript library alongside jQuery, we can return control of $ back to the other library with a call to $.noConflict():

it would be helpful for the inquisitive developer to understand a little more of what happens under the hood, so that they can be assured it will work as expected.

Maybe something like this...
If we need to use another JavaScript library alongside jQuery, we can return control of $ back to the other library with a call to $.noConflict(). Old references of $ are saved during jQuery initialization; noConflict() simply restores them.

Looking at the docs for jQuery.when here's the first example:

$.when( $.ajax("test.aspx") ).then(function(ajaxArgs){ 
     alert(ajaxArgs[1]); /* ajaxArgs is [ "success", statusText, jqXHR ] */
});

But when testing this... ajaxArgs is not an array. Instead, it's the response's data!

Here's a fiddle for testing: http://jsfiddle.net/mrazzari/XDbS7/

the first demo on the page http://api.jquery.com/all-selector/ is wrong. there should be only 10 elements found.
please check.

Hi,

Use callbacks.add example in jQuery.Callbacks.

Or don't call fn1 in fn2 and place outputs in new lines.

To me looks like calling callbacks.fire("bar"), runs only fn2 that call fn1.

Then I read and read again to understand. :)

Thanks

We state that shorthand properties such as border and background are not supported in the getter. While setting these properties works fine with most values, resetting does not. When setting shorthand properties to empty string in IE, they are nullified and previous styles are lost.

e.g.

$elem.css({
  "background": "",
  "border": ""
});

Hello,
i'd like to add to the documentation page about ID selector
an information that despite there should be only one such id in the page source,
selector will return you an array with one element.
Overall, documentation about id selector makes strong impression
that it will return a single element and that is not correct.

Best greeitings,
Paweł Wielgus.

Maybe add note at username and password saying that authentication is not possible with JSONP. Currently it's not said at all on the page, even though there is lots of JSONP related stuff scattered around.

http://api.jquery.com/jQuery.ajax/

Maybe this is a bug in jQuery too, as trying to do authentication with JSONP silently fails (and does not set any request parameters, since it's not possible). Warning message would be nice!

Greetings from Kumpula,
Sampumon

I did a quick and dirty transform so we would have something for the excerpt field:
https://github.com/jquery/api.jquery.com/blob/master/entries2html.xsl#L107-115

However, it doesn't get everything from the <desc> node as it should. Instead, it stops when it encounters a tag inside of it.

My xsl-fu is not strong enough to figure out how to do this, but basically we need to import the xml2json template and then apply it to the contents of that <desc> node (which is the value of the excerpt prop.

Not sure if this counts as a bug, but when finding parents of a collection of more than one element the resulting collection has the parents in a back-to-front order at each tier. e.g

<div class="div1"><span></span></div><div class="div2"><span></span></div>

$("span").parents() // [div2, div1, body, html]
                    // expected [div1, div2, body, html]

Test case: http://jsfiddle.net/vkGEQ/
Original ticket: http://bugs.jquery.com/ticket/11385

Team notes

This is by design , but the docs should mention it.

There appears to be a missing </strong> tag in entries/jQuery.ajax.xml, brought to my attention by the xmllint task failing when running grunt.

The site does a great job getting picked up by google, but it's not always easy to go from the side to finding the code in the repo... which I find myself doing frequently. So, it would be nice to have links from the doc to the code.

.slideDown()

• Categories: Effects > Sliding
• Defined in: effects.js

Bonus

• Hierarchy: jquery / src / effects.js
• Line number

I'm wondering what the plans are to support localized versions of the jQuery api documentation, if any. An initial effort could be made to automatically create localized versions in various languages through the use of a service like Google or Bing translate, and then add them to the repo in separate folders, maintained individually. Manual changes could then be accepted from real people. New APIs would need to be added to each locale's content as they are documented. Of course this could be somewhat automated over time.

Version: jQuery 1.7.2

Reading the documentation about the contentType it says the default value is "application/x-www-form-urlencoded" but the real default value is "application/x-www-form-urlencoded; charset=UTF-8".

I'm raising this because the documentation is confusing when it states that "data will always be transmitted to the server using UTF-8 charset".

If you change the value to "application/json" it won't be transmitted in UTF-8, will be ISO-8859-1 instead (the HTTP standard default).
You have to set it to "application/json; charset=UTF-8" for it to work properly.

It all comes down to not explaining those things in the documentation and stating that the default value is "application/x-www-form-urlencoded" when is not!!.

Thanks
Juan

When writing a custom selector and giving it a function as the rule, returning truthy from the function passes the check, and returning falsy fails. That is the case unless the function returns undefined. Although undefined is falsy, the check is considered to have passed.

While I think any such function should return a strict BOOL, there is no official documentation (that I can find, anyway) on how a custom selector should be written and what these functions should be returning.

This stems from a trouble ticket opened to TinyMCE ( http://www.tinymce.com/develop/bugtracker_view.php?id=4975 ). I believe they need to correct their function to return BOOL, but I felt this should be brought to the attention of the jQuery core team as it could be happening in many other places.

See this fiddle: http://jsfiddle.net/Pw43h/
Ticket: http://bugs.jquery.com/ticket/11246

Notes

We should update the documentation to make it clear that a boolean is necessary.

All of the animation methods accept an object containing duration, easing, callback but this signature isn't documented for any methods.

According to the rules of English, 'is' is used with a single object, and 'are' with multiple objects or no objects (zero). Hence, the code in the first example of the :checked selector documentation should read $("div").text(n + (n == 1 ? " is" : " are") + " checked!"); and not $("div").text(n + (n != 1 ? " is" : " are") + " checked!");

The description lists an Array of strings as a valid argument, but the XML feed does not.

In Chrome, IE7/8, and Opera the height value is floored to the nearest integer. In Firefox it is rounded. This leads to constant 1px discrepencies between Firefox and the rest of the world.

This only applies to elements after they are added to the DOM. Elements that exist as fragments will accept and set their height to a decimal until it is necessary to calculate their box size.

I'm not particularly certain that this should necessarily be changed in jQuery, since it is a bug/oddity within Firefox, but it would be convenient, at least, to report this discrepancy. I couldn't dig up any standard that details the correct behavior for this.

Test case from OP: http://jsfiddle.net/vju9B/3/
Simplified test case: http://jsfiddle.net/fbRUh/
Original ticket: http://bugs.jquery.com/ticket/11401

Team Notes:

Some of the differences in browsers concerning decimal point values should be respected for the sake of animations, if nothing else. We should not hide these.

http://jsfiddle.net/timmywil/fbRUh/3/

However, we could make a note in the docs for dimensions.

Ported from: http://bugs.jquery.com/ticket/11253

The description of the :parent selector reads: Select all elements that are the parent of another element, including text nodes.

http://api.jquery.com/parent-selector/

Suppose you have: <div> <p id="secret">jQuery is evil!</p> </div>

It is not clear what jQuery("p:parent") matches. Does it match the div, i.e. the paragraph's parent? Or does it match the paragraph?

The answer is that :parent matches the paragraph. This can be deducted from observation of other selector constructs and the realization that a selector doing the former would be :parent(p), but this is far from obvious. It is not clear that :parent means "is a parent", but not "the parent of". Some have even suggested to rename the selector in the documentation comments. I don't know if this is desirable, but kk and Jakub Konecki suggested ":hasChild" and ":isParent". I did find it very surprising to read that ":parent"'s opposite was ":empty".

Furthermore, the current description implies that text nodes are elements, which is misleading.

A description which would fix both issues would be: Select all elements that have a child node (either an element or text).

Ported from: http://bugs.jquery.com/ticket/11385

It should be noted in the docs that .parents() will order latest siblings first, not just closest parents first.

http://jsfiddle.net/timmywil/vkGEQ/2/

Original issue:

.serialize() does not serialize form elements inside a fieldset in Chrome or IE9.

To reproduce the issue, open the test case in the following browsers: Firefox, Chrome, and IE 9.

fails: Chrome and IE 9 on Windows 7 64-bit. works: Firefox on Windows 7 64-bit

OP test case: http://jsfiddle.net/HQZts/
Ticket: http://bugs.jquery.com/ticket/11594

Notes:

• It doesn't seem like this is a documented use of the method. The .serialize() method can act on a jQuery object that has selected individual form elements, such as , <textarea>, and . However, it is typically easier to select the tag itself for serialization ... http://api.jquery.com/serialize/. So other than a form, there is no current use of .serialize() that requires the code to search inside an element for more elements to process. (from adam) This could perhaps be phased in terms of explaining that "a collection that contains an element that contains form elements is not the same as a collection that contains form elements." Using the word "represent" is probably misleading here.

If I use .animate({ opacity: 0.32 }), nothing happens in IE8, but there is no such problem in other browsers (Chrome, Safari, Firefox, Opera, IE7, IE9).

OP test case: http://jsfiddle.net/ZVdaq/13/
Simplified test case: http://jsfiddle.net/mofle/ZVdaq/17/
Ticket: http://bugs.jquery.com/ticket/11188

Notes:

• Looks like the problem occurs without jQuery too, so it's definitely not a jQuery bug. IE8 opacity filter does not want to apply to child elements with position set. I you add "filter: inherit" on the child CSS, the filter applies.A fix would be to set "filter: inherit" on all descendants that has position set, but that would probably be an massive performance bottleneck. If there are no other solutions for this, I think we should just document it somewhere.
• We could normalize the behaviour so that it behaves as expected in the test case above, but I'm tempted to second the notion that filter:inherit could be a perf issue.

From https://forum.jquery.com/topic/add-more-jump-links-to-the-documentation

We'll have to take care to generate unique ids for semantic (and pretty) hashlinks

The index page should provide an overview of the docs, mention which version the docs apply to, where to find older versions, link to intro tutorials on the learn site, etc.

We've documented (for a while) that we would be deprecating success and error as per:

The jqXHR.success(), jqXHR.error(), and jqXHR.complete() callbacks will be deprecated in jQuery 1.8. To prepare your code for their eventual removal, use jqXHR.done(), jqXHR.fail(), and jqXHR.always() instead.

I didn't notice these in the initial release notes for 1.8b so just thought I'd bring it to someones attention. I believe Dave is going to file a ticket on the tracker so we can discuss it further / update the docs if needed.

The documentation - http://api.jquery.com/jQuery.isEmptyObject/ - states:

Description: Check to see if an object is empty (contains no properties).

This description is not correct. The function in question returns true if the given object doesn't contain any enumerable properties. However, the object may contain non-enumerable properties, and the function in question will in that case still return true.

This fact contradicts with the description in the docs, which states that the function returns true only if the given object doesn't contain any properties.

The description should at least state "(contains no enumerable properties)".

As it stands currently, $.proxy is in a weird place. It's likely too advanced of a tool for the average user, and crippled for advanced users. It lacks the ability to partially apply arguments and doesn't take advantage of native implementations where available. As well, $.proxy is being used internally to set matching guids (in $.fn.bind and $.fn.toggle), which is an unnecessary performance hit as well as reliance on an indirect side-effect of $.proxy.

The proposal is to:

• Make $.proxy spec-compatible.
• Use native implementations where available.
• Remove the non-standard object/key syntax (breaking).

Original ticket: http://bugs.jquery.com/ticket/7783

Notes:

@gf3 originally made a PR against this. The remaining work docs work should cover the latest behaviour after the removal of Function.prototype.bind jquery/jquery@15da298

Display function signatures / params on the index page.

Title of each method could display the signatures in a foldout box, etc. - for example, automatically display foldout box containing the first 3 signatures, or hover to display popout, etc.

If there are more than three signatures, indicate with an ellipsis; display remaining signatures on click of the foldout box.

Provide a bookmark for links to method signatures, for quick reference links (ie, for use in stackoverflow.)

From Dave:

The pages for APIs like .html() don't mention this problem, in fact we don't even mention that scripts injected via .html() are executed so I'm adding a needsdocs here. (Of course, just about any API that accepts HTML strings does this but it might surprise some devs.)

More info on this thread: http://bugs.jquery.com/ticket/11773

Go to http://api.jquery.com/browser/, click Events, Live Events, Live. You will see a link to a page on sitepoint. It is stale. New link appears to be http://www.sitepoint.com/javascript-event-delegation-is-easier-than-you-think/