Improved docs for append, prepend, before and after, merging the three pairs into one

diff --git a/newandnoteworthy.txt b/newandnoteworthy.txt
index cf8dcd5..89f757a 100644 (file)
--- a/newandnoteworthy.txt
+++ b/newandnoteworthy.txt
@@ -19,6 +19,7 @@ New and Noteworthy
  - You can now unbind event handlers from within themselves
  - Documented filter(Function)
  - Improved docs for FX module, merging method descriptions and marking optional arguments
+ - Improved docs for append, prepend, before and after, merging the three pairs into one
 
 1.0.4
 -----

diff --git a/src/jquery/coreTest.js b/src/jquery/coreTest.js
index d1035cf..c24bda0 100644 (file)
--- a/src/jquery/coreTest.js
+++ b/src/jquery/coreTest.js
@@ -170,8 +170,8 @@ test("wrap(String|Element)", function() {
        ok( result.text() == defaultText, 'Check for element wrapping' );\r
 });\r
 \r
-test("append(String|Element|Array<Element>)", function() {\r
-       expect(4);\r
+test("append(String|Element|Array<Element>|jQuery)", function() {\r
+       expect(5);\r
        var defaultText = 'Try them out:'\r
        var result = $('#first').append('<b>buga</b>');\r
        ok( result.text() == defaultText + 'buga', 'Check if text appending works' );\r
@@ -186,10 +186,15 @@ test("append(String|Element|Array&lt;Element&gt;)", function() {
        expected = "This link has class=\"blog\": Simon Willison's WeblogTry them out:Yahoo";\r
        $('#sap').append([document.getElementById('first'), document.getElementById('yahoo')]);\r
        ok( expected == $('#sap').text(), "Check for appending of array of elements" );\r
+       \r
+       reset();\r
+       expected = "This link has class=\"blog\": Simon Willison's WeblogTry them out:Yahoo";\r
+       $('#sap').append($("#first, #yahoo"));\r
+       ok( expected == $('#sap').text(), "Check for appending of jQuery object" );\r
 });\r
 \r
-test("prepend(String|Element|Array&lt;Element&gt;)", function() {\r
-       expect(4);\r
+test("prepend(String|Element|Array&lt;Element&gt;|jQuery)", function() {\r
+       expect(5);\r
        var defaultText = 'Try them out:'\r
        var result = $('#first').prepend('<b>buga</b>');\r
        ok( result.text() == 'buga' + defaultText, 'Check if text prepending works' );\r
@@ -204,10 +209,15 @@ test("prepend(String|Element|Array&lt;Element&gt;)", function() {
        expected = "Try them out:YahooThis link has class=\"blog\": Simon Willison's Weblog";\r
        $('#sap').prepend([document.getElementById('first'), document.getElementById('yahoo')]);\r
        ok( expected == $('#sap').text(), "Check for prepending of array of elements" );\r
+       \r
+       reset();\r
+       expected = "Try them out:YahooThis link has class=\"blog\": Simon Willison's Weblog";\r
+       $('#sap').prepend($("#first, #yahoo"));\r
+       ok( expected == $('#sap').text(), "Check for prepending of jQuery object" );\r
 });\r
 \r
-test("before(String|Element|Array&lt;Element&gt;)", function() {\r
-       expect(3);\r
+test("before(String|Element|Array&lt;Element&gt;|jQuery)", function() {\r
+       expect(4);\r
        var expected = 'This is a normal link: bugaYahoo';\r
        $('#yahoo').before('<b>buga</b>');\r
        ok( expected == $('#en').text(), 'Insert String before' );\r
@@ -221,10 +231,15 @@ test("before(String|Element|Array&lt;Element&gt;)", function() {
        expected = "This is a normal link: Try them out:diveintomarkYahoo";\r
        $('#yahoo').before([document.getElementById('first'), document.getElementById('mark')]);\r
        ok( expected == $('#en').text(), "Insert array of elements before" );\r
+       \r
+       reset();\r
+       expected = "This is a normal link: Try them out:diveintomarkYahoo";\r
+       $('#yahoo').before($("#first, #mark"));\r
+       ok( expected == $('#en').text(), "Insert jQuery before" );\r
 });\r
 \r
-test("after(String|Element|Array&lt;Element&gt;)", function() {\r
-       expect(3);\r
+test("after(String|Element|Array&lt;Element&gt;|jQuery)", function() {\r
+       expect(4);\r
        var expected = 'This is a normal link: Yahoobuga';\r
        $('#yahoo').after('<b>buga</b>');\r
        ok( expected == $('#en').text(), 'Insert String after' );\r
@@ -238,6 +253,11 @@ test("after(String|Element|Array&lt;Element&gt;)", function() {
        expected = "This is a normal link: YahooTry them out:diveintomark";\r
        $('#yahoo').after([document.getElementById('first'), document.getElementById('mark')]);\r
        ok( expected == $('#en').text(), "Insert array of elements after" );\r
+       \r
+       reset();\r
+       expected = "This is a normal link: YahooTry them out:diveintomark";\r
+       $('#yahoo').after($("#first, #mark"));\r
+       ok( expected == $('#en').text(), "Insert jQuery after" );\r
 });\r
 \r
 test("end()", function() {\r

diff --git a/src/jquery/jquery.js b/src/jquery/jquery.js
index 9840418..ebf9828 100644 (file)
--- a/src/jquery/jquery.js
+++ b/src/jquery/jquery.js
@@ -600,8 +600,8 @@ jQuery.fn = jQuery.prototype = {
        },
 
        /**
-        * Append any number of elements to the inside of every matched elements,
-        * generated from the provided HTML.
+        * Append content to the inside of every matched element.
+        *
         * This operation is similar to doing an appendChild to all the
         * specified elements, adding them into the document.
         *
@@ -609,40 +609,21 @@ jQuery.fn = jQuery.prototype = {
         * @before <p>I would like to say: </p>
         * @result <p>I would like to say: <b>Hello</b></p>
         *
-        * @name append
-        * @type jQuery
-        * @param String html A string of HTML, that will be created on the fly and appended to the target.
-        * @cat DOM/Manipulation
-        */
-
-       /**
-        * Append an element to the inside of all matched elements.
-        * This operation is similar to doing an appendChild to all the
-        * specified elements, adding them into the document.
-        *
         * @example $("p").append( $("#foo")[0] );
         * @before <p>I would like to say: </p><b id="foo">Hello</b>
         * @result <p>I would like to say: <b id="foo">Hello</b></p>
         *
-        * @name append
-        * @type jQuery
-        * @param Element elem A DOM element that will be appended.
-        * @cat DOM/Manipulation
-        */
-
-       /**
-        * Append any number of elements to the inside of all matched elements.
-        * This operation is similar to doing an appendChild to all the
-        * specified elements, adding them into the document.
-        *
         * @example $("p").append( $("b") );
         * @before <p>I would like to say: </p><b>Hello</b>
         * @result <p>I would like to say: <b>Hello</b></p>
         *
         * @name append
         * @type jQuery
-        * @param Array<Element> elems An array of elements, all of which will be appended.
+        * @param <Content> content Content to append to the target
         * @cat DOM/Manipulation
+        * @see prepend(<Content>)
+        * @see before(<Content>)
+        * @see after(<Content>)
         */
        append: function() {
                return this.domManip(arguments, true, 1, function(a){
@@ -651,94 +632,59 @@ jQuery.fn = jQuery.prototype = {
        },
 
        /**
-        * Prepend any number of elements to the inside of every matched elements,
-        * generated from the provided HTML.
-        * This operation is the best way to insert dynamically created elements
-        * inside, at the beginning, of all the matched element.
+        * Prepend content to the inside of every matched element.
+        *
+        * This operation is the best way to insert elements
+        * inside, at the beginning, of all matched elements.
         *
         * @example $("p").prepend("<b>Hello</b>");
         * @before <p>I would like to say: </p>
         * @result <p><b>Hello</b>I would like to say: </p>
         *
-        * @name prepend
-        * @type jQuery
-        * @param String html A string of HTML, that will be created on the fly and appended to the target.
-        * @cat DOM/Manipulation
-        */
-
-       /**
-        * Prepend an element to the inside of all matched elements.
-        * This operation is the best way to insert an element inside, at the
-        * beginning, of all the matched element.
-        *
         * @example $("p").prepend( $("#foo")[0] );
         * @before <p>I would like to say: </p><b id="foo">Hello</b>
         * @result <p><b id="foo">Hello</b>I would like to say: </p>
-        *       
-        * @name prepend
-        * @type jQuery
-        * @param Element elem A DOM element that will be appended.
-        * @cat DOM/Manipulation
-        */
-
-       /**
-        * Prepend any number of elements to the inside of all matched elements.
-        * This operation is the best way to insert a set of elements inside, at the
-        * beginning, of all the matched element.
-        *
+        *      
         * @example $("p").prepend( $("b") );
         * @before <p>I would like to say: </p><b>Hello</b>
         * @result <p><b>Hello</b>I would like to say: </p>
         *
         * @name prepend
         * @type jQuery
-        * @param Array<Element> elems An array of elements, all of which will be appended.
+        * @param <Content> content Content to prepend to the target.
         * @cat DOM/Manipulation
+        * @see append(<Content>)
+        * @see before(<Content>)
+        * @see after(<Content>)
         */
        prepend: function() {
                return this.domManip(arguments, true, -1, function(a){
                        this.insertBefore( a, this.firstChild );
                });
        },
-
+       
        /**
-        * Insert any number of dynamically generated elements before each of the
-        * matched elements.
+        * Insert content before each of the matched elements.
         *
         * @example $("p").before("<b>Hello</b>");
         * @before <p>I would like to say: </p>
         * @result <b>Hello</b><p>I would like to say: </p>
         *
-        * @name before
-        * @type jQuery
-        * @param String html A string of HTML, that will be created on the fly and appended to the target.
-        * @cat DOM/Manipulation
-        */
-
-       /**
-        * Insert an element before each of the matched elements.
-        *
         * @example $("p").before( $("#foo")[0] );
         * @before <p>I would like to say: </p><b id="foo">Hello</b>
         * @result <b id="foo">Hello</b><p>I would like to say: </p>
         *
-        * @name before
-        * @type jQuery
-        * @param Element elem A DOM element that will be appended.
-        * @cat DOM/Manipulation
-        */
-
-       /**
-        * Insert any number of elements before each of the matched elements.
-        *
         * @example $("p").before( $("b") );
         * @before <p>I would like to say: </p><b>Hello</b>
         * @result <b>Hello</b><p>I would like to say: </p>
         *
         * @name before
         * @type jQuery
-        * @param Array<Element> elems An array of elements, all of which will be appended.
+        * @param <Content> content Content to insert before each target.
         * @cat DOM/Manipulation
+        * @see append(<Content>)
+        * @see prepend(<Content>)
+        * @see after(<Content>)
         */
        before: function() {
                return this.domManip(arguments, false, 1, function(a){
@@ -747,43 +693,27 @@ jQuery.fn = jQuery.prototype = {
        },
 
        /**
-        * Insert any number of dynamically generated elements after each of the
-        * matched elements.
+        * Insert content after each of the matched elements.
         *
         * @example $("p").after("<b>Hello</b>");
         * @before <p>I would like to say: </p>
         * @result <p>I would like to say: </p><b>Hello</b>
         *
-        * @name after
-        * @type jQuery
-        * @param String html A string of HTML, that will be created on the fly and appended to the target.
-        * @cat DOM/Manipulation
-        */
-
-       /**
-        * Insert an element after each of the matched elements.
-        *
         * @example $("p").after( $("#foo")[0] );
         * @before <b id="foo">Hello</b><p>I would like to say: </p>
         * @result <p>I would like to say: </p><b id="foo">Hello</b>
         *
-        * @name after
-        * @type jQuery
-        * @param Element elem A DOM element that will be appended.
-        * @cat DOM/Manipulation
-        */
-
-       /**
-        * Insert any number of elements after each of the matched elements.
-        *
         * @example $("p").after( $("b") );
         * @before <b>Hello</b><p>I would like to say: </p>
         * @result <p>I would like to say: </p><b>Hello</b>
         *
         * @name after
         * @type jQuery
-        * @param Array<Element> elems An array of elements, all of which will be appended.
+        * @param <Content> content Content to insert after each target.
         * @cat DOM/Manipulation
+        * @see append(<Content>)
+        * @see prepend(<Content>)
+        * @see before(<Content>)
         */
        after: function() {
                return this.domManip(arguments, false, -1, function(a){
@@ -796,6 +726,8 @@ jQuery.fn = jQuery.prototype = {
         * back to its previous state. After an end operation, the list of matched elements will
         * revert to the last state of matched elements.
         *
+        * If there was no destructive operation before, an empty set is returned.
+        *
         * @example $("p").find("span").end();
         * @before <p><span>Hello</span>, how are you?</p>
         * @result $("p").find("span").end() == [ <p>...</p> ]