From 9a805fd2401b7ff0ff322de1c27701e305aebbd4 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Fri, 6 Nov 2026 08:50:29 +0100
Subject: [PATCH] docs: name the methods that count an export

adding-a-platform listed what a format can hold and none of what counts the written file. lands, states, fills, clears, names_anew and withheld are what seven exporters override so the summary matches the diff; a test reads the page for every one an exporter overrides.
---
 tests/test_exporters.py   | 20 ++++++++++++++++++++
 wiki/adding-a-platform.md | 22 ++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/tests/test_exporters.py b/tests/test_exporters.py
index 9f7f9565b..251b31966 100644
--- a/tests/test_exporters.py
+++ b/tests/test_exporters.py
@@ -2909,6 +2909,26 @@ class BatoceraNotesStayWithTheirItem(unittest.TestCase):
         self.assertEqual(trailing, {("bios/bk0010.zip", "two.rom"): "# tail"})
 
 
+class TheWikiNamesWhatCountsAnExport(unittest.TestCase):
+    """adding-a-platform listed the methods that say what a format can hold
+    and none of those that count what render wrote, which seven exporters
+    override so the report matches the diff."""
+
+    def test_every_overridden_contract_method_is_documented(self):
+        documented = ("carries", "requires", "can_add", "keys_by_system",
+                      "lands", "states", "fills", "clears", "names_anew", "withheld")
+        overridden = {
+            name
+            for cls in discover_exporters().values()
+            for name in documented
+            if name in vars(cls)
+        }
+        wiki = (REPO_ROOT / "wiki" / "adding-a-platform.md").read_text(encoding="utf-8")
+        for name in sorted(overridden):
+            with self.subTest(method=name):
+                self.assertIn(f"`{name}(", wiki)
+
+
 class BatoceraEntriesAtAnyIndent(unittest.TestCase):
     """EmuELEC indents 23 of its systems with one tab. The entry pattern
     required four spaces, so each was appended again whole and the export
diff --git a/wiki/adding-a-platform.md b/wiki/adding-a-platform.md
index 8da75e437..add851786 100644
--- a/wiki/adding-a-platform.md
+++ b/wiki/adding-a-platform.md
@@ -606,6 +606,28 @@ of files:
   own system, so an entry filed under one of our system ids is never written.
 - `needs_original()` - `True` as soon as `native_sources()` names a file.
 
+Those methods say what the format could hold. The report counts what `render()`
+actually wrote, through a second set, read entry by entry:
+
+- `lands(fe)` - whether the entry is in the written file. Defaults to
+  `writable()`. Override it when `render()` drops an entry the format could
+  hold: RetroBat merges an addition into a path it already declares, and
+  System.dat leaves out a file with no section name.
+- `states(fe, field)` - whether the written entry carries the corrected field.
+  Defaults to `field in carries()`.
+- `fills(fe, field)` and `clears(fe, field)` - whether a hash only the truth
+  names is written, and whether a hash the truth contradicts leaves the entry.
+  Both default to `states()`.
+- `names_anew(fe)` - whether the render wrote, for the first time, a file the
+  platform already declares. Only a format whose unit is not the entry needs it
+  (a RetroPie help sentence).
+- `withheld()` - corrections the render proved and still did not write, named
+  so the run does not read as nothing to do.
+
+An exporter whose `render()` skips anything the defaults count must override
+the matching method. Otherwise the summary announces a change the maintainer
+will not find in the diff.
+
 ### Round-trip validation
 
 The scraper and the exporter are checked against each other as