Correct documentation of callback arguments

[jugglinmike]

The described behavior is implemented by jQuery 2.x but not jQuery 1.x. I think this is a bug because the documentation already describes the argument type for these callback functions: see $.fn.after and $.fn.before. If a maintainer could confirm this, I'd be happy to follow up with a patch for jQuery 1.x.

Commit message:

Both $.fn.before and $.fn.after invoke the supplied function with
two arguments: the numeric index of each element in the set and the
string markup describing each element's contents. The type of these
arguments is correctly documented, but the description of the second
argument is omitted. Include this information based on the documentation
for similar behavior in $.fn.append.

[gnarf]

I'm not sure if that second argument to that callback was defined before 2.x.

We could bring the 1.x up to compatibility, but I think we'd want to document the minimum supported version(s) for the second argument if it is currently missing in 1.x branch.

[jugglinmike]

Thanks, Corey! I'd be happy to update the patch to accomodate, but it sounds like we need to verify that this is new to 2.x . @esx introduced the documentation for the second argument in January of this year.

@tjvantoll do you know if this is new to jQuery 2.x ? If so, how would you like me to denote this argument as "2.x and up" in this patch?

[tjvantoll]

I'm not seeing any difference in the behavior of 1.x and 2.x—http://jsfiddle.net/tj_vantoll/gs32f3m0/. I think it makes sense to add this mention of the second argument, although I would use “HTML contents” to refer to its value rather than “old HTML value”.

[gnarf]

It works in jQuery 1.10 (http://jsfiddle.net/gnarf/gs32f3m0/2/) but not 1.9(http://jsfiddle.net/gnarf/gs32f3m0/3/)

[gnarf]

@kswedberg - do you know how we can document that the second argument to this callback is only present in jQuery 1.10+ / jQuery 2.0+ ?

[scottgonzalez]

Remove the second argument from the existing signature and add a new signature with the correct version in the <added> element.

[kswedberg]

yeah, 👍 to what @scottgonzalez said. The new signature should have <added>1.10</added>.

[jugglinmike]

@tjvantoll I copied that wording from the equivalent documentation on $.fn.append. I like your wording better, but that change should probably happen in a separate pull request that addresses all occurences (e.g. prepend as well).

[jugglinmike]

@kswedberg @scottgonzalez Thanks to you both! I've updated the patch according to your feedback and split it into two commits (one for each method). I have not verified the output by building the site myself, though--would one of the maintainers mind doing this on my behalf?

[gnarf]

I feel like this should maybe be before the other signature (or maybe it doesn't matter shrug)

[kswedberg]

Looks good to me, @jugglinmike. I pulled it and tested a build with no problems. Will merge shortly. Thanks!

[jugglinmike]

My pleasure :)