From 76618af460c519a2fcffb9309874cd9a215b71f6 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Wed, 21 Oct 2026 05:24:34 +0200
Subject: [PATCH] docs: shorten two script docstrings

_enrich_hashes repeated "ground truth" five times with capitalised
insistence for a three-step lookup, and the MAME ZIP rebuild listed
three guarantees of which two were the same.
---
 scripts/generate_pack.py   | 12 +++---------
 scripts/truth.py           | 25 +++++--------------------
 tests/test_doc_surfaces.py | 17 +++++++++++++++++
 3 files changed, 25 insertions(+), 29 deletions(-)

diff --git a/scripts/generate_pack.py b/scripts/generate_pack.py
index 56975f37..c87eb5e1 100644
--- a/scripts/generate_pack.py
+++ b/scripts/generate_pack.py
@@ -1252,16 +1252,10 @@ class DamagedArchiveError(OSError):
 def _normalize_zip_for_pack(
     source_zip: str, dest_path: str, target_zf: zipfile.ZipFile
 ) -> None:
-    """Add a MAME BIOS ZIP to the pack as a deterministic rebuild.
+    """Add a MAME BIOS ZIP to the pack, rebuilt from its ROMs.
 
-    Instead of copying the original ZIP (with non-deterministic metadata),
-    extracts the ROM atoms, rebuilds the ZIP deterministically, and writes
-    the normalized version into the pack.
-
-    This ensures:
-    - Same ROMs -> same ZIP hash in every pack build
-    - No dependency on how the user built their MAME ROM set
-    - Bit-identical ZIPs across platforms and build times
+    The same ROMs give the same archive bytes in every build, whatever
+    metadata the source ZIP carried.
     """
     import tempfile as _tmp
 
diff --git a/scripts/truth.py b/scripts/truth.py
index dc569291..d8835970 100644
--- a/scripts/truth.py
+++ b/scripts/truth.py
@@ -39,27 +39,13 @@ def _serialize_source_ref(sr: object) -> str:
 
 
 def _enrich_hashes(entry: dict, db: dict) -> None:
-    """Fill missing sibling hashes from the database, ground-truth preserving.
+    """Fill the hashes a profile omits from the record its own hash names.
 
-    The profile's hashes come from the emulator source code (ground truth).
-    Any hash of a given file set of bytes is a projection of that same
-    ground truth. sha1, md5 and crc32 all identify the same bytes. If the
-    profile has ONE ground-truth hash, the DB can supply its siblings.
-
-    Lookup order (all are hash-anchored, never name-based):
-      1. SHA1 direct
-      2. MD5 -> SHA1 via indexes.by_md5
-      3. CRC32 -> SHA1 via indexes.by_crc32 (weaker 32-bit anchor,
-         requires size match when profile has size)
-
-    Name-based enrichment is NEVER used: a name alone has no ground-truth
-    anchor, the file in bios/ may not match what the source code expects.
-
-    Multi-hash entries (lists of accepted variants) are left untouched to
-    preserve variant information.
+    The record is found by sha1, then md5, then crc32 with the size when the
+    profile gives one. Never by name: a file in bios/ under the same name may
+    not be the bytes the source code expects. An entry listing several
+    accepted values for a hash is left as is.
     """
-    # Skip multi-hash entries. They express ground truth as "any of these N
-    # variants", enriching with a single sibling would lose that information.
     for h in ("sha1", "md5", "crc32"):
         if isinstance(entry.get(h), list):
             return
@@ -105,7 +91,6 @@ def _enrich_hashes(entry: dict, db: dict) -> None:
         return
 
     # Copy sibling hashes and size from the anchored record.
-    # These are projections of the same ground-truth bytes.
     for field in ("sha1", "md5", "sha256", "crc32"):
         if not entry.get(field) and record.get(field):
             entry[field] = record[field]
diff --git a/tests/test_doc_surfaces.py b/tests/test_doc_surfaces.py
index 35737c3e..c2118164 100644
--- a/tests/test_doc_surfaces.py
+++ b/tests/test_doc_surfaces.py
@@ -249,6 +249,23 @@ class NoHedgedRules(unittest.TestCase):
         self.assertEqual(offenders, [], "\n".join(offenders))
 
 
+class DocstringsWithoutInsistence(unittest.TestCase):
+    """truth.py shouted ONE and NEVER in an eighteen-line docstring, and
+    generate_pack.py listed three guarantees under 'This ensures:' of which
+    two said the same thing."""
+
+    TICS = re.compile(r"\b(NEVER|ALWAYS|ONE|MUST)\b|This ensures:")
+
+    def test_scripts_and_installer(self):
+        offenders = []
+        paths = sorted((ROOT / "scripts").rglob("*.py")) + [ROOT / "install.py"]
+        for path in paths:
+            for line in _python_prose(path.read_text(encoding="utf-8")).splitlines():
+                if self.TICS.search(line):
+                    offenders.append(f"{path.relative_to(ROOT)}: {line.strip()[:80]}")
+        self.assertEqual(offenders, [], "\n".join(offenders))
+
+
 class PeerToneTowardPlatforms(unittest.TestCase):
     """Platform lists were called wrong, stale or corrected on public pages
     that their maintainers read."""