Adding documenation to qunit callbacks for handling promises

docs/callbacks/QUnit.begin.md

@@ -8,7 +8,7 @@ categories:
 
 ## `QUnit.begin( callback )`
 
-Register a callback to fire whenever the test suite begins.
+Register a callback to fire whenever the test suite begins. The callback can return a promise that will be waited for before the next callback is handled.
 
 `QUnit.begin()` is called once before running any tests.
 
@@ -39,3 +39,14 @@ QUnit.begin( ( { totalTests } ) => {
   console.log( `Test amount: ${totalTests}` );
 });
 ```
+
+Returning a promise:
+
+```js
+QUnit.begin( () => {
+  return new Promise(function(resolve, reject) {
+    // do some async work
+    resolve();
+  });
+});
+```

docs/callbacks/QUnit.done.md

@@ -8,7 +8,7 @@ categories:
 
 ## `QUnit.done( callback )`
 
-Register a callback to fire whenever the test suite ends.
+Register a callback to fire whenever the test suite ends. The callback can return a promise that will be waited for before the next callback is handled.
 
 | parameter | description |
 |-----------|-------------|
@@ -40,3 +40,14 @@ QUnit.done( ( { total, failed, passed, runtime } ) => {
   console.log( `Total: ${total}, Failed: ${failed}, Passed: ${passed}, Runtime: ${runtime}` );
 });
 ```
+
+Returning a promise:
+
+```js
+QUnit.done( () => {
+  return new Promise(function(resolve, reject) {
+    // do some async work
+    resolve();
+  });
+});
+```

docs/callbacks/QUnit.log.md

@@ -17,6 +17,8 @@ The properties of the details argument are listed below as options.
 |-----------|-------------|
 | callback (function) | Callback to execute. Provides a single argument with the callback details object |
 
+**NOTE: Callback in QUnit.log() does not handle promises and must be synchronous.**
+
 #### Callback details: `callback( details: { result, actual, expected, message, source, module, name, runtime, todo } )`
 
 | parameter | description |

docs/callbacks/QUnit.moduleDone.md

@@ -8,7 +8,7 @@ categories:
 
 ## `QUnit.moduleDone( callback )`
 
-Register a callback to fire whenever a module ends.
+Register a callback to fire whenever a module ends. The callback can return a promise that will be waited for before the next callback is handled.
 
 | parameter | description |
 |-----------|-------------|
@@ -40,4 +40,15 @@ Using modern syntax:
 QUnit.moduleDone( ( { name, failed, total } ) => {
   console.log( `Finished running: ${name} Failed/total: ${failed}, ${total}` );
 });
-```
+```
+
+Returning a promise:
+
+```js
+QUnit.moduleDone( () => {
+  return new Promise(function(resolve, reject) {
+    // do some async work
+    resolve();
+  });
+});
+```

docs/callbacks/QUnit.moduleStart.md

@@ -8,7 +8,7 @@ categories:
 
 ## `QUnit.moduleStart( callback )`
 
-Register a callback to fire whenever a module begins.
+Register a callback to fire whenever a module begins. The callback can return a promise that will be waited for before the next callback is handled.
 
 | parameter | description |
 |-----------|-------------|
@@ -37,3 +37,14 @@ QUnit.moduleStart( ( { name } ) => {
   console.log( `Now running: ${name}` );
 });
 ```
+
+Returning a promise:
+
+```js
+QUnit.moduleStart( () => {
+  return new Promise(function(resolve, reject) {
+    // do some async work
+    resolve();
+  });
+});
+```

docs/callbacks/QUnit.on.md

@@ -17,6 +17,8 @@ Register a callback to fire whenever the specified event is emitted. Conforms to
 | eventName (string) | The name of the event for which to execute the provided callback. |
 | callback (function) | Callback to execute. Receives a single argument representing the data for the event. |
 
+**NOTE: Callback in QUnit.on() does not handle promises and must be synchronous.**
+
 ### Example
 
 Printing results of a test suite.

docs/callbacks/QUnit.testDone.md

@@ -8,7 +8,7 @@ categories:
 
 ## `QUnit.testDone( callback )`
 
-Register a callback to fire whenever a test ends.
+Register a callback to fire whenever a test ends. The callback can return a promise that will be waited for before the next callback is handled.
 
 | parameter | description |
 |-----------|-------------|
@@ -70,3 +70,14 @@ QUnit.testDone( ( { module, name, total, passed, failed, skipped, todo, runtime
   console.log( JSON.stringify( result, null, 2 ) );
 } );
 ```
+
+Returning a promise:
+
+```js
+QUnit.testDone( () => {
+  return new Promise(function(resolve, reject) {
+    // do some async work
+    resolve();
+  });
+});
+```

docs/callbacks/QUnit.testStart.md

@@ -8,7 +8,7 @@ categories:
 
 ## `QUnit.testStart( callback )`
 
-Register a callback to fire whenever a test begins.
+Register a callback to fire whenever a test begins. The callback can return a promise that will be waited for before the next callback is handled.
 
 | parameter | description |
 |-----------|-------------|
@@ -40,3 +40,14 @@ QUnit.testStart( ( { module, name } ) => {
   console.log( `Now running: ${module}: ${name}` );
 });
 ```
+
+Returning a promise:
+
+```js
+QUnit.testStart( () => {
+  return new Promise(function(resolve, reject) {
+    // do some async work
+    resolve();
+  });
+});
+```