Entries: Added assert.async. Deprecated start, stop, and asyncTest

Fixes #72
Fixes #73
Fixes #74
Fixes #79
Closes #82
Closes #92

entries/QUnit.asyncTest.xml

@@ -14,18 +14,21 @@
 		</argument>
 	</signature>
 	<desc>
-		Add an asynchronous test to run. The test must include a call to QUnit.start().
+		DEPRECATED: Add an asynchronous test to run. The test must include a call to QUnit.start().
 	</desc>
 	<longdesc>
+		<p class="warning">
+			This method is <strong>deprecated</strong>. It is recommended to use <a href="/QUnit.test/"><code>QUnit.test()</code></a> in conjunction with <a href="/async/"><code>assery.async()</code></a> instead.
+		</p>
 		<p>For testing asynchronous code, <code>QUnit.asyncTest</code> will automatically stop the test runner and wait for your code to call <a href="/QUnit.start/"><code>QUnit.start()</code></a> to continue.</p>
 		<p>The <a href="/QUnit.assert/"><code>assert</code></a> argument to the callback contains all of QUnit's <a href="/category/assert/">assertion methods</a>. Use this argument to call your test assertions.</p>
-		<p>This method used to have an optional second argument called <code>expected</code>. This argument is deprecated and its usage will start throwing errors in 2.0.0. If you're using it, use <a href="/expect"><code>expect()</code></a> instead.</p>
+		<p>This method used to have an optional second argument called <code>expected</code>, which was also deprecated. If you are currently using it, use <a href="/expect/"><code>assert.expect()</code></a> instead.</p>
 	</longdesc>
 	<example height="250">
-		<desc>The following illustrates an asynchronous test that waits 1 second before resuming</desc>
+		<desc>The following illustrates an asynchronous test that waits 1 second before resuming.</desc>
 <code><![CDATA[
 QUnit.asyncTest( "asynchronous test: one second later!", function( assert ) {
-	expect( 1 );
+	assert.expect( 1 );
 
 	setTimeout(function() {
 		assert.ok( true, "Passed and ready to resume!" );
@@ -38,7 +41,7 @@ QUnit.asyncTest( "asynchronous test: one second later!", function( assert ) {
 		<desc>A more practical example that must wait for a video element to be loaded before running any assertions.</desc>
 <code><![CDATA[
 QUnit.asyncTest( "asynchronous test: video ready to play", function( assert ) {
-	expect( 1 );
+	assert.expect( 1 );
 	var $video = $( "video" );
 
 	$video.on( "canplaythrough", function() {

entries/QUnit.start.xml

@@ -4,17 +4,21 @@
 	<title>QUnit.start()</title>
 	<signature>
 		<argument name="decrement" type="Integer" optional="true">
-			<desc>Optional argument to merge multiple start() calls into one. Use with multiple corresponding stop() calls.</desc>
+			<desc>DEPRECATED: Optional argument to merge multiple start() calls into one. Use with multiple corresponding stop() calls.</desc>
 		</argument>
 	</signature>
 	<desc>
-		Start running tests again after the testrunner was stopped. See <a href="/QUnit.stop/"><code>QUnit.stop()</code></a>.
+		PARTIALLY DEPRECATED: Start running tests again after the testrunner was stopped. See <a href="/QUnit.stop/"><code>QUnit.stop()</code></a> and <code><a href="/QUnit.config/">QUnit.config</a>.autostart</code>.
 	</desc>
 	<longdesc>
+		<p class="warning">
+			This method is <strong><em>partially</em> deprecated</strong>. For use within tests, it is recommended to use <a href="/async/"><code>assert.async</code></a> instead.
+		</p>
 		<p>When your async test has multiple exit points, call <code>QUnit.start()</code> for the corresponding number of <a href="/QUnit.stop/"><code>QUnit.stop()</code></a> increments.</p>
+		<p>Additionally, <code>QUnit.start()</code> must be used to start a test run that has <code><a href="/QUnit.config/">QUnit.config</a>.autostart</code> set to <code>false</code>.</p>
 	</longdesc>
 	<example height="250">
-		<desc>A test that waits 150ms for an async operation to finish, then asserts the result.</desc>
+		<desc>DEPRECATED: A test that waits 150ms for an async operation to finish, then asserts the result.</desc>
 <code><![CDATA[
 QUnit.test( "a test", function( assert ) {
 	QUnit.stop();
@@ -24,6 +28,14 @@ QUnit.test( "a test", function( assert ) {
 		QUnit.start();
 	}, 150 );
 });
+]]></code>
+	</example>
+	<example>
+		<desc>A test run that does not begin when the page is done loading. This example uses an Asynchronous Module Definition (AMD) loader-style <code>require</code> call.</desc>
+<code><![CDATA[
+QUnit.config.autostart = false;
+
+require(["test/tests1.js", "test/tests2.js"], QUnit.start);
 ]]></code>
 	</example>
 

entries/QUnit.stop.xml

@@ -7,12 +7,15 @@
 			<desc>Optional argument to increase the async test depth with multiple steps at once.</desc>
 		</argument>
 	</signature>
-	<desc>Increase the number of <a href="/QUnit.start/"><code>QUnit.start()</code></a> calls the testrunner should wait for before continuing.</desc>
+	<desc>DEPRECATED: Increase the number of <a href="/QUnit.start/"><code>QUnit.start()</code></a> calls the testrunner should wait for before continuing.</desc>
 	<longdesc>
+		<p class="warning">
+			This method is <strong>deprecated</strong>. It is recommended to use <a href="/async/"><code>assert.async</code></a> instead.
+		</p>
 		<p>When your async test has multiple exit points, call <code>QUnit.stop()</code> multiple times or use the increment argument.</p>
 	</longdesc>
 	<example height="250">
-		<desc>A test that waits 150ms for an async operation to finish, then asserts the result.</desc>
+		<desc>DEPRECATED: A test that waits 150ms for an async operation to finish, then asserts the result.</desc>
 <code><![CDATA[
 QUnit.test( "a test", function( assert ) {
 	QUnit.stop();
@@ -24,5 +27,6 @@ QUnit.test( "a test", function( assert ) {
 });
 ]]></code>
 	</example>
+
 	<category slug="async-control"/>
 </entry>

entries/async.xml

@@ -0,0 +1,47 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
+<entry type="method" name="async">
+  <title>async()</title>
+  <desc>
+    Instruct QUnit to wait for an asynchronous operation.
+  </desc>
+  <longdesc>
+    <p>When your test has any asynchronous exit points, call <code>assert.async()</code> to get a unique resolution callback for each async operation. The callback returned from <code>assert.async()</code> will throw an Error if is invoked more than once.</p>
+    <p>This replaces functionality previously provided by <a href="/QUnit.stop/"><code>QUnit.stop()</code></a> and <a href="/QUnit.start/"><code>QUnit.start()</code></a>.</p>
+  </longdesc>
+  <example height="250">
+  <desc>Tell QUnit to wait for the <code>done()</code> call inside the timeout.</desc>
+<code><![CDATA[
+QUnit.test( "assert.async() test", function( assert ) {
+  var done = assert.async();
+  var input = $( "#test-input" ).focus();
+  setTimeout(function() {
+    assert.equal( document.activeElement, input[0], "Input was focused" );
+    done();
+  });
+});
+]]></code>
+  </example>
+  <example height="250">
+  <desc>Call <code>assert.async()</code> for each operation. Each <code>done</code> callback can be called at most once.</desc>
+<code><![CDATA[
+QUnit.test( "two async calls", function( assert ) {
+  assert.expect( 2 );
+
+  var done1 = assert.async();
+  var done2 = assert.async();
+  setTimeout(function() {
+    assert.ok( true, "test resumed from async operation 1" );
+    done1();
+  }, 500 );
+  setTimeout(function() {
+    assert.ok( true, "test resumed from async operation 2" );
+    done2();
+  }, 150);
+});
+]]></code>
+  </example>
+
+  <category slug="assert"/>
+  <category slug="async-control"/>
+</entry>