From 41558399e3c2f876bfcb5e66f7fa72baf188f3cb Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 26 Jul 2026 00:25:43 +0200
Subject: [PATCH] Standardized some arguments labels throughout the Playdate
 bindings target.

---
 README.md                                              | 3 ++-
 Sources/PlaydateKit/JSON/JSON.swift                    | 2 +-
 Sources/PlaydateKit/Sound/Synth/Classes/Sequence.swift | 4 ++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 85f11f8..5bad8ff 100644
--- a/README.md
+++ b/README.md
@@ -253,7 +253,7 @@ try save.write(JSON.encode(.table([
 ])))
 try save.close()
 
-let loaded = try JSON.decodeFile(at: "save.json")
+let loaded = try JSON.decodeFile(path: "save.json")
 if case .table(let entries) = loaded, case .int(let level)? = entries["level"] {
     Game.shared.level = level
 }
@@ -301,6 +301,7 @@ try Lua.addFunction(double, name: "mylib.double")
 
 - **Namespaces.** The subsystem namespaces (`System`, `Graphics`, `Sound`, …) live at the top level of the module; only the raw C API bootstrap stays under `Playdate` (`Playdate.initialize(with:)`, `Playdate.api`). On a name collision with another module, qualify with the module name: `PlaydateKit.System`.
 - **Properties vs. methods.** State the OS can report back is a property: read-write where the C API has a get/set pair (`Display.refreshRate`, `Source.volume`), get-only where it only has a getter (`Display.fps`). A `set…` method means the C API is write-only there (`Display.setScale`, `Synth.setAttackTime`) or setting takes extra arguments — a property getter never invents a value the OS can't return. Callbacks are installed with `set…Callback`/`set…Function` methods.
+- **Paths.** APIs that load a single file label the argument `path:` (`Bitmap(path:)`, `JSON.decodeFile(path:)`); directory operations use `at:` (`File.listFiles(at:)`). The POSIX-named `File.stat`, `File.mkdir`, and `File.unlink` take their path unlabeled, like their C namesakes.
 - **Errors.** Fallible operations use typed throws — `throws(PlaydateError)` generally, `throws(Network.NetError)` for network I/O — so `catch` gives you a concrete type, and no `any Error` existentials are needed.
 - **Ownership.** A wrapper that *creates* a C object frees it on `deinit`; keep the wrapper referenced for as long as you use it. Wrappers vending OS-owned objects (a `Bitmap` from a `BitmapTable`, a track from a `Sequence`, …) don't free them — keep the owner alive instead, as documented on each API. Resources a C object keeps referencing (a sprite's image, a synth's sample, modulators, menu-item option titles) are retained by the wrapper automatically.
 - **Callbacks.** Where the C API provides a userdata slot, closures are supported everywhere and delivered back with the right wrapper. A few C callbacks have no userdata (serial messages, headphone changes, scoreboard
diff --git a/Sources/PlaydateKit/JSON/JSON.swift b/Sources/PlaydateKit/JSON/JSON.swift
index 9b3a42f..88ccea0 100644
--- a/Sources/PlaydateKit/JSON/JSON.swift
+++ b/Sources/PlaydateKit/JSON/JSON.swift
@@ -150,7 +150,7 @@ extension JSON {
     }
 
     /// Opens and decodes the JSON file at `path`.
-    public static func decodeFile(at path: String) throws(PlaydateError) -> Value {
+    public static func decodeFile(path: String) throws(PlaydateError) -> Value {
         let file = try File.Handle(path: path, mode: [.read, .readData])
         return try decode(file: file)
     }
diff --git a/Sources/PlaydateKit/Sound/Synth/Classes/Sequence.swift b/Sources/PlaydateKit/Sound/Synth/Classes/Sequence.swift
index b21779d..cc72c78 100644
--- a/Sources/PlaydateKit/Sound/Synth/Classes/Sequence.swift
+++ b/Sources/PlaydateKit/Sound/Synth/Classes/Sequence.swift
@@ -15,9 +15,9 @@ extension Sound {
         }
 
         /// Creates a sequence and loads the MIDI file at `path`.
-        public convenience init(midiFilePath: String) throws(PlaydateError) {
+        public convenience init(path: String) throws(PlaydateError) {
             self.init()
-            try loadMIDIFile(path: midiFilePath)
+            try loadMIDIFile(path: path)
         }
 
         deinit {