Sorry, but the extra arguments are documented as of a couple days ago. Would it be possible to do a "plain object" check on the second arg and do your thing if it passes? That way we could leave the other multi-arg signature in place.

i understand they may be documented as of very recently, but they are not in wide use yet. therefore, it is not too late to un-document them in my opinion. i just don't see added benefit in having this at all, the signature itself is unlike 90% if not 99% of other jquery methods, and creates a scaffold for future method-cruft with a poor precedent.

of course it's possible to have that special-case check. but i agree with

Dave Methvin that a special case is not worth it. this would worse still than a bad, but predictable API.

these multiple arguments were never a trumpeted feature, and unveiling them so unceremoniously, then calling it finalized in its current state does not sit well with me at all.

I don't see a compelling need for additional signatures, they just make the API harder to understand. We all can certainly come up with new ones but unless there are significant benefits I would prefer to maintain backward compatibility.

Also there is code that depends on multi-arg, here's an imperfect search for it:

http://google.com/codesearch?hl=en&lr=&q=\\.(ap|pre)pend\\([^()]*,+lang:javascript+-extjs+-ckeditor

certainly this is not for any 1.5.x release, but leaving it undocumented (as before) would ease an already easy migration to maybe a 1.6 target - wrapping the arguments with an array is a trivial regex replace.

fear of breaking backwards compatibility of previously undocumented features is a strange concern at best. and an even stranger reason to retain what exists currently when it can easily be replicated in a more optimal manner.

i think this is a mistake going forward, not much else i can say.

$0.02 given

I don't think it's a strange concern to keep an API that was introduced in jQuery 1.0. However, I've studied the manipulation code and do not believe it is very difficult to extend the api for append/prepend and even other dom manipulation methods as they all use the same function, as kswedberg has already suggested. See third party Pull Request

We're keeping the multi-arg form of .append and friends since it has been around for five years.