[Request] Make API naming more consistent

[joshgoebel]

Our API for the most part is consistent with it's naming using two primary naming forms:

• [verb]... blit, start, update, trace...
• (implied verb) [noun]... such as tone (play tone), line (draw line)...

One understands why the verb is implied simply to save typing... Yet we have two API functions that don't follow either pattern:

diskr (destPtr, size)
diskw (srcPtr, size)

I suggest these be rethought and renamed to bring them in line with the other API calls. Also do we really have a "disk"? Wouldn't it be more likely it's EEPROM, flash, some sort of a save game micro-cartridge, etc?

---

Noun form doesn't work here since the verb is unclear... so we need verb form or [verb][noun]... I realize we're trying to do that already with [noun][first letter of verb]... I guess it just feels out of place to me and doesn't match the rest of the API IMHO.

Suggestions:

• persist (save)
• savedata (load)

Or paired:

• saveData
• loadData
• writeEEPROM
• readEEPROM
• writePersistent
• readPersistent

Or if we have the concepts right, just fix the naming:

• readDisk
• writeDisk

[FaberVitale]

I suggest these be rethought and renamed to bring them in line with the other API calls.

Are you suggesting breaking changes or you want to alias those functions?

[joshgoebel]

Well given #239 I think breaking changes are needed anyways (unless we just add NEW functions for partial writes and reads). Someone said we're "alpha" on Discord and I agreed (based on how young the project is), yet our version number seems to be 2.0 already, which is - wow (given our age). The intent here was to suggest breaking changes because I did not at the time realize we were "released" software yet... so better to break the eggs early.

I guess that's up to @aduros now what the policy is on breaking changes..

And ALSO another open question is if we care about source or binary compatibility (which are two different things)...

[joshgoebel]

Or perhaps disk* stay as the "read/write entire disk" API (if we can't do breaking changes) and we add a more nuanced API for #239.

Still I'd consider this renaming for v3 (when theoretically we could break things) [if anyone agreed it's a good idea]...

[christopher-kleine]

My two cents on this: Good for pointing that out. We don't want WASM-4 to end like the PHP for FCs, right? About the suggested function names:

• persist (save) / savedata (load) : Sorry, that's confusing. The name "savedata" doesn't imply loading at all.
• saveData / loadData : Good idea. With one caveat: save and load from where? This could also mean from RAM for all the name implies.
• writeEEPROM / readEEPROM : Now, that's a bit too specific and kinda hard to remember.
• writePersistent / readPersistent : Good. A clear name with the a clearly stated purpose.
• readDisk / writeDisk : My favourite so far. Simple and short name. And "disk" in general is a persistent device. A disk doesn't have to be a HDD. You'd still say "store the document on disk" even if it's a SSD.

About the version number: Yes, I think we should slow this down a bit. We can hardly claim "We're in Alpha" and at the same time have major version 95 or so. We're way younger than TIC-80, Go, Elm and so on. And we're nowhere near as mature as those projects. Yet, none of them is anywhere near v2. Go the closest with v1.17 ATM. I know it's impossible at this point in time, but I'd like to see a version even below v1 for now. Since - like we said - we're not stable yet.