I noticed what I consider to be a bug in the documentation, but rather than quietly fix it, I'm posting to this group because I think it might be part of a larger issue.
The bug is in the documentation of $.fn.serialize() and $.fn.serializeArray(). serialize(), unbeknownst to me until I looked at the source of the method, is a sugar method. All it does is call $.param() on the result of serializeArray(). The docs for serialize() say nothing about param() nor serializeArray(). http://docs.jquery.com/Ajax/serialize If I had found the documentation for serialize() by browsing the list of ajax functions, rather than searching for serialize, I would have noticed the serializeArray() function. However, it would have only gave me part of the answer. I could use serializeArray() to get the fields, but according to it, I "must use a plugin or third-party library to stringify". This is not true: $.param() is available without installing any plugins. http://docs.jquery.com/Ajax/serializeArray http://docs.jquery.com/Utilities/jQuery.param There are two reasons I'd like to see sugar methods to be documented as such. First, it would make learning jQuery quicker if you could learn about the sugar methods in the context of the main methods. Second, if you're working on an existing piece of code that uses a sugar method and you need more flexibility, having it documented as a sugar method makes it easier to translate. For example, I'd like for the docs to explain how to get the same effect as get(), post(), getJSON(), and getScript() by using the ajax() function, so I can convert a call to any of them to a call to ajax() if I need to. I also think it would be neat if somehow methods could be tagged as convenience methods so someone who just wants to see what jQuery is capable of can skip over the convenience methods. Thoughts? Ben Atkin
