From 581d7c88bea4216fb47c2a98f38af59f2d14485d Mon Sep 17 00:00:00 2001
From: Silvan Mosberger <silvan.mosberger@tweag.io>
Date: Tue, 18 Jul 2023 17:20:28 +0200
Subject: lib/tests: Unify documentation of individual testable files

---
 lib/path/tests/prop.sh |  7 +++++--
 lib/tests/misc.nix     | 18 +++++++++++++++---
 lib/tests/modules.sh   |  8 +++++++-
 lib/tests/sources.sh   |  7 +++++++
 4 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/lib/path/tests/prop.sh b/lib/path/tests/prop.sh
index e48c6667fa0..d6021cfcd5f 100755
--- a/lib/path/tests/prop.sh
+++ b/lib/path/tests/prop.sh
@@ -1,9 +1,12 @@
 #!/usr/bin/env bash
 
-# Property tests for the `lib.path` library
-#
+# Property tests for lib/path/default.nix
 # It generates random path-like strings and runs the functions on
 # them, checking that the expected laws of the functions hold
+# Run:
+# [nixpkgs]$ lib/path/tests/prop.sh
+# or:
+# [nixpkgs]$ nix-build lib/tests/release.nix
 
 set -euo pipefail
 shopt -s inherit_errexit
diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix
index 231f19c513e..6dc0d391fb4 100644
--- a/lib/tests/misc.nix
+++ b/lib/tests/misc.nix
@@ -1,6 +1,18 @@
-# to run these tests:
-# nix-instantiate --eval --strict nixpkgs/lib/tests/misc.nix
-# if the resulting list is empty, all tests passed
+/*
+Nix evaluation tests for various lib functions.
+
+Since these tests are implemented with Nix evaluation, error checking is limited to what `builtins.tryEval` can detect, which is `throw`'s and `abort`'s, without error messages.
+If you need to test error messages or more complex evaluations, see ./modules.sh, ./sources.sh or ./filesystem.sh as examples.
+
+To run these tests:
+
+  [nixpkgs]$ nix-instantiate --eval --strict lib/tests/misc.nix
+
+If the resulting list is empty, all tests passed.
+Alternatively, to run all `lib` tests:
+
+  [nixpkgs]$ nix-build lib/tests/release.nix
+*/
 with import ../default.nix;
 
 let
diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index 7aebba6b589..5c596b5a668 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -1,7 +1,13 @@
 #!/usr/bin/env bash
-#
+
 # This script is used to test that the module system is working as expected.
+# Executing it runs tests for `lib.modules`, `lib.options` and `lib.types`.
 # By default it test the version of nixpkgs which is defined in the NIX_PATH.
+#
+# Run:
+# [nixpkgs]$ lib/tests/modules.sh
+# or:
+# [nixpkgs]$ nix-build lib/tests/release.nix
 
 set -o errexit -o noclobber -o nounset -o pipefail
 shopt -s failglob inherit_errexit
diff --git a/lib/tests/sources.sh b/lib/tests/sources.sh
index cda77aa96b2..079c7eea565 100755
--- a/lib/tests/sources.sh
+++ b/lib/tests/sources.sh
@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+
+# Tests lib/sources.nix
+# Run:
+# [nixpkgs]$ lib/tests/sources.sh
+# or:
+# [nixpkgs]$ nix-build lib/tests/release.nix
+
 set -euo pipefail
 shopt -s inherit_errexit
 
-- 
cgit 1.4.1