From 05827969cdef2684fd910104fc8f05a0657a3eab Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinkle@fastmail.com>
Date: Thu, 11 Jul 2024 02:25:31 +0100
Subject: [PATCH] Docs: Improve test.if() and test.skip() documentation

* Make explicit that test.if() behaves as if deciding between
  test and test.skip.

* Clarify that skip() callback is optional, and has been since
  QUnit 1.0.0.
---
 docs/api/QUnit/test.if.md   | 17 +++++++++++++++++
 docs/api/QUnit/test.skip.md | 11 ++++++++---
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/docs/api/QUnit/test.if.md b/docs/api/QUnit/test.if.md
index 42cad5ce5..96c1a86e4 100644
--- a/docs/api/QUnit/test.if.md
+++ b/docs/api/QUnit/test.if.md
@@ -27,6 +27,8 @@ As a codebase becomes bigger, you may need to conditionally skip an entire group
 
 ## Examples
 
+### Skip a test
+
 ```js
 QUnit.module('MyApp');
 
@@ -36,6 +38,21 @@ QUnit.test.if('render', typeof document !== 'undefined', function (assert) {
 });
 ```
 
+This is equivalent to:
+
+```js
+// Skip if executed without a DOM
+if (typeof document !== 'undefined') {
+  QUnit.test('render', function (assert) {
+    assert.strictEqual(MyApp.render(), '<p>Hello world!</p>');
+  });
+} else {
+  QUnit.test.skip('render');
+}
+```
+
+### Conditional module
+
 ```js
 QUnit.module.if('MyApp', typeof document !== 'undefined');
 
diff --git a/docs/api/QUnit/test.skip.md b/docs/api/QUnit/test.skip.md
index a6ef9a1cc..65e746997 100644
--- a/docs/api/QUnit/test.skip.md
+++ b/docs/api/QUnit/test.skip.md
@@ -11,15 +11,17 @@ redirect_from:
 version_added: "1.16.0"
 ---
 
+`QUnit.test.skip( name )`<br/>
 `QUnit.test.skip( name, callback )`<br/>
+`QUnit.skip( name )`<br/>
 `QUnit.skip( name, callback )`
 
 Add a test that will be skipped during the run.
 
 | parameter | description |
 |-----------|-------------|
-| `name` (string) | Title of unit being tested |
-| `callback` (function) | Function that performs the test |
+| `name` (string) | Title of unit |
+| `callback` (function) | Optional, function that would perform the test |
 
 Use this method to disable a [`QUnit.test()`](./test.md), as alternative to commenting out the test.
 
@@ -38,7 +40,7 @@ As a codebase becomes bigger, you may sometimes want to temporarily disable an e
 
 ## Examples
 
-How to use `skip` as a placeholder for future or temporarily broken tests.
+How to use `skip` as a placeholder for future tests, or to temporarily skip a broken test.
 
 ```js
 QUnit.module('robot', hooks => {
@@ -55,5 +57,8 @@ QUnit.module('robot', hooks => {
   QUnit.test.skip('laser', assert => {
     assert.true(robot.laser());
   });
+
+  // TODO: Implement this later!
+  QUnit.test.skip('jump');
 });
 ```