From 37a5bd05ff900e31ca6965542f211d8b68a26e92 Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Wed, 21 Oct 2026 05:10:45 +0200 Subject: [PATCH] docs: state .info facts in profile notes Ten notes and comments called .info entries phantom, misleading or incorrectly written. They now say what the .info declares and what the code reads, and a prose test refuses those verdicts in profiles. --- emulators/ep128emu.yml | 2 +- emulators/ep128emu_core.yml | 6 +++--- emulators/fbalpha2012_cps1.yml | 4 ++-- emulators/freeintv_ts_overlay.yml | 14 ++++++++------ emulators/mess2015.yml | 2 +- emulators/neocd.yml | 3 ++- emulators/np2kai.yml | 5 +++-- emulators/stella.yml | 4 ++-- emulators/vice_xscpu64.yml | 8 ++++---- emulators/x1.yml | 3 ++- tests/test_prose_style.py | 22 ++++++++++++++++++++++ 11 files changed, 50 insertions(+), 23 deletions(-) diff --git a/emulators/ep128emu.yml b/emulators/ep128emu.yml index b3b2e91d..a5f4f1a3 100644 --- a/emulators/ep128emu.yml +++ b/emulators/ep128emu.yml @@ -206,7 +206,7 @@ files: # epd19hft.rom and zt19hfnt.rom: listed in .info (firmware8, firmware9) but # NOT referenced in core source code and NOT in builtin_rom map (roms.hpp:46516-46538). - # The core never loads these files. Excluded from profile to avoid misleading users. + # The core never loads these files, so the profile does not list them. # ============================================================ # Videoton TVC diff --git a/emulators/ep128emu_core.yml b/emulators/ep128emu_core.yml index 9ea9eb8a..d8153038 100644 --- a/emulators/ep128emu_core.yml +++ b/emulators/ep128emu_core.yml @@ -26,9 +26,9 @@ notes: >- auto-detected and determines machine configuration and ROM selection. Custom ROM mappings are possible via .ep128cfg config files placed in ep128emu/config/ or next to content. The .info declares epd19hft.rom - and zt19hfnt.rom which are phantom entries never referenced in code. - The .info omits epdos16f.rom and exdos14isdos10uk.rom which are used - by the code. SDEXT, ReSID, and MIDI port features are compile-disabled + and zt19hfnt.rom, and no code path in the core opens either file. The + .info does not list epdos16f.rom and exdos14isdos10uk.rom, which the + code loads. SDEXT, ReSID, and MIDI port features are compile-disabled in the libretro build. files: diff --git a/emulators/fbalpha2012_cps1.yml b/emulators/fbalpha2012_cps1.yml index 5f226557..7931815e 100644 --- a/emulators/fbalpha2012_cps1.yml +++ b/emulators/fbalpha2012_cps1.yml @@ -28,8 +28,8 @@ notes: | ROM path: ROMs are loaded from the content directory (g_rom_dir). system_directory (libretro.cpp:2202) is used only for hiscore.dat. - The .info note "BIOS files must be inside the ROM directory" is misleading: - there are no BIOS files for CPS-1. This note is generic across all FBA cores. + The .info note "BIOS files must be inside the ROM directory" is the note + each FB Alpha 2012 .info carries. CPS-1 loads no BIOS file. 244 ROM sets defined (488 STD_ROM_PICK/FN entries = 244 games). is_experimental=false, need_fullpath=true, block_extract=true. diff --git a/emulators/freeintv_ts_overlay.yml b/emulators/freeintv_ts_overlay.yml index 9435413b..44b4171a 100644 --- a/emulators/freeintv_ts_overlay.yml +++ b/emulators/freeintv_ts_overlay.yml @@ -19,12 +19,14 @@ notes: | upstream. The Makefile produces freeintv_libretro (TARGET_NAME = freeintv), and library_name is "freeintv" (src/libretro.c:1413). - The FreeIntvTSOverlay_libretro.info in libretro-core-info has errors: - wrong overlay directory (claims FreeIntvTS_Overlays, code uses - freeintv_overlays), wrong dimensions (claims 300x670, code uses 370x600), - phantom external PNG files (controller_base.png, default.png, - button_swapscreen.png are either embedded in C headers or nonexistent), - and firmware1 key typos (uses firmware0_path/firmware0_opt). + FreeIntvTSOverlay_libretro.info asks for 300x670 overlay PNGs in + FreeIntvTS_Overlays, next to controller_base.png, default.png and + button_swapscreen.png. The code reads + /freeintv_overlays/.png with a 370x600 default + (src/libretro.c, build_overlay_path and overlay_width/overlay_height), + decodes the controller frame and the default keypad from + src/keypad_frame_graphic.h and src/default_keypad_image.h, and opens no + file named button_swapscreen.png. bios_identical_to: freeintv diff --git a/emulators/mess2015.yml b/emulators/mess2015.yml index 5a55c255..9b513f60 100644 --- a/emulators/mess2015.yml +++ b/emulators/mess2015.yml @@ -23,7 +23,7 @@ notes: | Software list support via 375 XML hash files in system_dir/mess2015/hash/. Hash files are bundled in the source repo at /hash/. Not on libretro buildbot. - .info incorrectly says SYSTEMDIR\ume\hash, the actual path is mess2015/hash. + The .info names SYSTEMDIR\ume\hash. The code reads mess2015/hash. hiscore.c integrated (libretro addition, not in upstream MAME 0.159). SAMPLES sound driver disabled in mess.mak. diff --git a/emulators/neocd.yml b/emulators/neocd.yml index fae255d5..6cc0b0d0 100644 --- a/emulators/neocd.yml +++ b/emulators/neocd.yml @@ -31,7 +31,8 @@ notes: | algorithmically, never loaded from file (src/memory.cpp:223-253 generateYZoomData, CRC32 E09E253C), so the core never opens these files. - .info firmware_count=12 but 2 are phantoms (Y-ZOOM), effective count=10. + .info declares firmware_count=12. The core reads 10 of them and builds + the two Y-ZOOM entries itself. .info lists uni-bioscd.rom as "Universe BIOS 3.2" but SHA1 matches Universe BIOS 3.3 (confirmed by GitHub README). diff --git a/emulators/np2kai.yml b/emulators/np2kai.yml index a7b88662..e86f43d0 100644 --- a/emulators/np2kai.yml +++ b/emulators/np2kai.yml @@ -20,8 +20,9 @@ systems: [pc-98] # always has a built-in BIOS simulator. itf.rom loading (bios.c:579) is dead # code behind #else of this define and is never executed. # -# .info declares firmware_count=11 but is incomplete: misses IDE, SCSI, SASI, -# PCI, GPIB ROMs and key.txt. Lists itf.rom which is dead code (phantom). +# .info declares firmware_count=11. It does not list the IDE, SCSI, SASI, +# PCI and GPIB ROMs or key.txt, and it lists itf.rom, which the core never +# loads (see above). # # The fmgen YM2608 rhythm engine (fmgen_opna.cpp:1415-1444) loads WAV files # with uppercase names (2608_BD.WAV), the built-in rhythm engine (rhythmc.c) diff --git a/emulators/stella.yml b/emulators/stella.yml index 97eaa220..eeab8549 100644 --- a/emulators/stella.yml +++ b/emulators/stella.yml @@ -13,6 +13,6 @@ systems: note: | Identical codebase to stella2014-libretro. Both repos share the same HEAD commit and produce a binary reporting library_name "Stella 2014". The - stella_libretro.info incorrectly lists display_version "6.6", while the actual - embedded version is 3.9.3. See stella2014.yml for firmware requirements + stella_libretro.info lists display_version "6.6", and the binary reports + 3.9.3. See stella2014.yml for firmware requirements and KidVid audio files. diff --git a/emulators/vice_xscpu64.yml b/emulators/vice_xscpu64.yml index 1d543706..51625423 100644 --- a/emulators/vice_xscpu64.yml +++ b/emulators/vice_xscpu64.yml @@ -17,10 +17,10 @@ notes: > scpu-dos-*.bin provide the original CMD SuperCPU DOS kernals, loaded from system/vice/SCPU64/ when SuperCPU Kernal core option is changed from Internal. JiffyDOS requires True Drive Emulation enabled and a non-internal SuperCPU - kernal (the internal ROM is not JiffyDOS-compatible). The .info incorrectly - declares JiffyDOS_C64.bin (firmware_count=4), but the C64 kernal replacement is - only loaded for x64/x64sc/x128, never for xscpu64. Correct firmware_count=5 - (2 SCPU64 kernals + 3 JiffyDOS drive DOSes). + kernal (the internal ROM is not JiffyDOS-compatible). The .info declares + JiffyDOS_C64.bin (firmware_count=4). The C64 kernal replacement is loaded + for x64/x64sc/x128 only, so xscpu64 reads 5 files: 2 SCPU64 kernals and 3 + JiffyDOS drive DOSes. files: - name: "scpu-dos-2.04.bin" diff --git a/emulators/x1.yml b/emulators/x1.yml index 69fe9f88..30e3cd07 100644 --- a/emulators/x1.yml +++ b/emulators/x1.yml @@ -40,7 +40,8 @@ systems: # to set the working dir. Fonts may not be found from xmil/ in practice. # # .info declares firmware_count=2 (IPL ROMs only). Font files are not declared. -# .info firmware1_desc incorrectly says "8x8 Font ROM" (actually Turbo IPL ROM). +# .info firmware1_desc reads "8x8 Font ROM". The core loads IPLROM.X1T as the +# Turbo IPL ROM. notes: | Place all files in: /xmil/ diff --git a/tests/test_prose_style.py b/tests/test_prose_style.py index e59c4d22..da1ecaeb 100644 --- a/tests/test_prose_style.py +++ b/tests/test_prose_style.py @@ -194,6 +194,28 @@ class NoToolingNames(unittest.TestCase): self.assertEqual(offenders, [], "\n".join(offenders[:20])) +class ProfilesStateFactsAboutOtherProjects(unittest.TestCase): + """A profile says what another project's file declares and what the code + does, never a verdict on that file. Ten notes and comments in ten profiles + called .info entries "phantom", "misleading" or "incorrectly" written, and + the site rendered them on the emulator pages.""" + + VERDICTS = re.compile( + r"\b(phantoms?|misleading|bogus|typos?|has errors|incorrectly " + r"(?:says|lists|declares|states|claims|names|describes))\b", + re.IGNORECASE, + ) + + def test_profile_prose_and_comments(self): + offenders = [ + f"{path.relative_to(ROOT)}: {line.strip()[:100]}" + for path in sorted((ROOT / "emulators").glob("*.yml")) + for line in _yaml_prose(path.read_text(encoding="utf-8")).splitlines() + if self.VERDICTS.search(line) + ] + self.assertEqual(offenders, [], "\n".join(offenders[:40])) + + class NoClauseSemicolons(unittest.TestCase): def _check(self, files: list[Path], extract) -> None: offenders = []