Docs: Modernize and improve documentation examples

* Docs: Modernize and improve documentation examples

* Use modern syntax by default.
  Keep a few alternative "classic ES5 syntax" examples,
  explicitly described as such.

* Consistent parameter naming test formatting.

* Make the examples for `assert.timeout`, `assert.async`, `assert.verifySteps`,
  and `assert.pushResult` more appealing by replacing them with something
  that seems more reflecting of current best practices.

* Point out that callback methods support async functions.

Author: Krinkle

.editorconfig

@@ -10,6 +10,6 @@ charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 
-[*.yml]
+[*.{yml,md}]
 indent_style = space
 indent_size = 2

docs/Gemfile

@@ -4,4 +4,7 @@ ruby RUBY_VERSION
 # To upgrade, run `bundle update github-pages`.
 gem "github-pages", group: :jekyll_plugins
 
+# Temporary fix for https://github.com/github/pages-gem/issues/752
+gem "webrick", "~> 1.7"
+
 gem 'jekyll-algolia', "1.6.0", group: :jekyll_plugins

docs/Gemfile.lock

@@ -9,9 +9,9 @@ GEM
       zeitwerk (~> 2.2, >= 2.2.2)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
-    algolia_html_extractor (2.6.2)
+    algolia_html_extractor (2.6.4)
       json (~> 2.0)
-      nokogiri (~> 1.10.4)
+      nokogiri (~> 1.10)
     algoliasearch (1.27.5)
       httpclient (~> 2.8, >= 2.8.3)
       json (>= 1.5.1)
@@ -223,22 +223,24 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.3.6)
-    mini_portile2 (2.4.0)
+    mini_portile2 (2.5.0)
     minima (2.5.1)
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
-    minitest (5.14.2)
+    minitest (5.14.3)
     multipart-post (2.1.1)
-    nokogiri (1.10.10)
-      mini_portile2 (~> 2.4.0)
+    nokogiri (1.11.1)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
     octokit (4.20.0)
       faraday (>= 0.9)
       sawyer (~> 0.8.0, >= 0.5.3)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     progressbar (1.11.0)
     public_suffix (3.1.1)
+    racc (1.5.2)
     rb-fsevent (0.10.4)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
@@ -271,6 +273,7 @@ GEM
     unf_ext (0.0.7.7)
     unicode-display_width (1.7.0)
     verbal_expressions (0.1.5)
+    webrick (1.7.0)
     zeitwerk (2.4.2)
 
 PLATFORMS
@@ -279,9 +282,10 @@ PLATFORMS
 DEPENDENCIES
   github-pages
   jekyll-algolia (= 1.6.0)
+  webrick (~> 1.7)
 
 RUBY VERSION
-   ruby 2.7.2p137
+   ruby 3.0.0p0
 
 BUNDLED WITH
-   2.1.4
+   2.2.3

docs/QUnit/start.md

@@ -16,14 +16,15 @@ version_added: "1.0"
 
 When your async test has multiple exit points, call `QUnit.start()` for the corresponding number of `QUnit.stop()` increments.
 
-### Example
+### Examples
 
 A test run that does not begin when the page is done loading. This example uses an Asynchronous Module Definition (AMD) loader-style `require` call.
 
 ```js
 QUnit.config.autostart = false;
 
-require(["test/tests1.js", "test/tests2.js"], function() {
-  QUnit.start();
-});
+require(
+  [ "test/tests1.js", "test/tests2.js" ],
+  QUnit.start
+);
 ```

docs/QUnit/test.only.md

@@ -41,7 +41,7 @@ When debugging a larger area of code, you may want to _only_ run all tests withi
 | [QUnit 2.12](https://github.com/qunitjs/qunit/releases/tag/2.12.0) | The `QUnit.only()` method was renamed to `QUnit.test.only()`.<br/>Use of `QUnit.only()` remains supported as an alias.
 | [QUnit 1.20](https://github.com/qunitjs/qunit/releases/tag/1.20.0) | The `QUnit.only()` method was introduced.
 
-### Example
+### Examples
 
 How to use `QUnit.test.only` to filter which tests are run.
 

docs/QUnit/test.skip.md

@@ -33,7 +33,7 @@ As a codebase becomes bigger, you may sometimes want to temporarily disable an e
 | [QUnit 2.12](https://github.com/qunitjs/qunit/releases/tag/2.12.0) | The `QUnit.skip()` method was renamed to `QUnit.test.skip()`.<br/>Use of `QUnit.skip()` remains supported as an alias.
 | [QUnit 1.16](https://github.com/qunitjs/qunit/releases/tag/1.16.0) | The `QUnit.skip()` method was introduced.
 
-### Example
+### Examples
 
 How to use `skip` as a placeholder for future or temporarily broken tests.
 

docs/QUnit/test.todo.md

@@ -39,7 +39,7 @@ You can also use [`QUnit.module.todo()`](./module.md) to manage the "todo" state
 | [QUnit 2.12](https://github.com/qunitjs/qunit/releases/tag/2.12.0) | The `QUnit.todo()` method was renamed to `QUnit.test.todo()`.<br/>Use of `QUnit.todo()` remains supported as an alias.
 | [QUnit 2.2](https://github.com/qunitjs/qunit/releases/tag/2.2.0) | The `QUnit.todo()` method was introduced.
 
-### Example
+### Examples
 
 How to use `QUnit.test.todo` to denote code that is still under development.
 

docs/assert/async.md

@@ -28,58 +28,72 @@ This replaces functionality previously provided by `QUnit.stop()` and [`QUnit.st
 
 ### Examples
 
-Tell QUnit to wait for the `done()` call inside the timeout.
+##### Example: Wait for callback
+
+Tell QUnit to wait for the `done()` call from a callback.
 
 ```js
-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" );
+function fetchDouble( num, callback ) {
+  const double = num * 2;
+  callback( double );
+}
+
+QUnit.test( "async example", assert => {
+  const done = assert.async();
+
+  fetchDouble( 21, res => {
+    assert.strictEqual( res, 42, "Result" );
     done();
   });
 });
 ```
+##### Example: Wait for multiple callbacks
 
-Call `assert.async()` for each operation. Each `done` callback can be called at most once.
+Call `assert.async()` multiple times to wait for multiple async operations. Each `done` callback must be called exactly once for the test to pass.
 
 ```js
-QUnit.test( "two async calls", function( assert ) {
-  assert.expect( 2 );
+QUnit.test( "two async calls", assert => {
+  const done1 = assert.async();
+  const done2 = assert.async();
 
-  var done1 = assert.async();
-  var done2 = assert.async();
-  setTimeout(function() {
-    assert.true( true, "test resumed from async operation 1" );
+  fetchDouble( 3, res => {
+    assert.strictEqual( res, 6, "double of 3" );
     done1();
-  }, 500 );
-  setTimeout(function() {
-    assert.true( true, "test resumed from async operation 2" );
+  });
+  fetchDouble( 9, res => {
+    assert.strictEqual( res, 18, "double of 9" );
     done2();
-  }, 150);
+  });
 });
 ```
 
-Set up an async test three exit points. Each `done()` call adds up to the `acceptCallCount`. After three calls, the test is done.
+##### Example: Require multiple calls
+
+The `acceptCallCount` parameter can be used to require multiple calls to the same callback. In the below exxample, the test passes after exactly three calls.
 
 ```js
-QUnit.test( "multiple call done()", function( assert ) {
-  assert.expect( 3 );
-  var done = assert.async( 3 );
+function uploadBatch(batch, notify, complete) {
+  batch.forEach( (item) => {
+    // Do something with item
+    notify();
+  });
+  complete(null)
+}
 
-  setTimeout(function() {
-    assert.true( true, "first call done." );
-    done();
-  }, 500 );
+QUnit.test( "acceptCallCount example", assert => {
+  assert.timeout( 1000 );
 
-  setTimeout(function() {
-    assert.true( true, "second call done." );
-    done();
-  }, 500 );
+  const notify = assert.async( 3 );
+  const done = assert.async();
 
-  setTimeout(function() {
-    assert.true( true, "third call done." );
-    done();
-  }, 500 );
+  uploadBatch(
+    [ "a", "b", "c" ],
+    notify,
+    (err) => {
+      assert.strictEqual( err, null, "complete error parameter" );
+
+      done();
+    }
+  );
 });
 ```

docs/assert/deepEqual.md

@@ -29,25 +29,29 @@ The `deepEqual()` assertion can be used just like `equal()` when comparing the v
 
 ### Examples
 
-Compare the value of two objects.
+Validate the properties and values of a given object.
+
 ```js
-QUnit.test( "deepEqual test", function( assert ) {
-  var obj = { foo: "bar" };
+QUnit.test( "good example", assert => {
+  const result = { foo: "bar" };
 
-  assert.deepEqual( obj, { foo: "bar" }, "Two objects can be the same in value" );
+  assert.deepEqual( result, { foo: "bar" }, "result object" );
 });
 ```
 
 ```js
-QUnit.test( 'deepEqual failing test', function( assert ) {
-  assert.deepEqual( {
-    a: 'Albert',
-    b: 'Berta',
+QUnit.test( "bad example", assert => {
+  const result = {
+    a: "Albert",
+    b: "Berta",
     num: 123
-  }, {
-    a: 'Albert',
-    b: 'Berta',
-    num: '123' // Fails: the number `123` is not strictly equal to the string `'123'`.
+  };
+
+  // fails because the number 123 is not strictly equal to the string "123".
+  assert.deepEqual( result, {
+    a: "Albert",
+    b: "Berta",
+    num: "123"
   } );
 } );
 ```

docs/assert/equal.md

@@ -13,7 +13,7 @@ version_added: "1.0"
 
 `equal( actual, expected [, message ] )`
 
-A non-strict value comparison.
+A non-strict comparison of two values.
 
 | name               | description                          |
 |--------------------|--------------------------------------|
@@ -25,6 +25,8 @@ A non-strict value comparison.
 
 The `equal` assertion uses the simple comparison operator (`==`) to compare the actual and expected arguments. When they are equal, the assertion passes; otherwise, it fails. When it fails, both actual and expected values are displayed in the test result, in addition to a given message.
 
+This method is similar to the `assertEquals()` method found in xUnit-style frameworks.
+
 [`notEqual()`](./notEqual.md) can be used to explicitly test inequality.
 
 [`strictEqual()`](./strictEqual.md) can be used to test strict equality.