Doc comments on Playdate API

[MrHaila]

Hey, and thanks a lot for this project! This is such a fun way look into both Zig and Playdate. Much appreciated.

While leafing through the graphics API in particular, I got quickly annoyed by jumping between the C docs and my code, so I spent a bit of time copy pasting text from API docs into the definitions file. A format like this ended up being useful for me as a newbie:

/// Gets various info about bitmap including its width and height and raw pixel data. The data is 1 bit per pixel packed format, in MSB order; in other words, the high bit of the first byte in data is the top left pixel of the image. If the bitmap has a mask, a pointer to its data is returned in mask, else NULL is returned.
///
/// https://sdk.play.date/2.3.1/Inside%20Playdate%20with%20C.html#f-graphics.getBitmapData
getBitmapData: *const fn (bitmap: ?*LCDBitmap, width: ?*c_int, height: ?*c_int, rowbytes: ?*c_int, mask: ?*[*c]u8, data: ?*[*c]u8) callconv(.C) void,

...so in VSC with the Zig language server running I get this:

This obviously feels like something that could be scraped but I'm just doing it by hand to actually read the stuff while I go.

So, is this (or something like it) useful enough to warrant a PR? Happy to contribute incase it's a worthy addition. Obviously makes the definitions file really verbose and probably needs that scraper to stay up-to-date with official updates 🤷‍♂️

[DanB91]

Hey, thanks for this! At first thought it would be great to add doc comments to the APIs. But yea, it would be something more to maintain, especially since the URL changes each update. We could have something in build.zig that generates the URL based on the latest version maintained. Which actually would give insight into how often this repo is updated.

But it adds more complexity and indirection to the repo since we'd be generating the API zig file, which I'd like to avoid. Let me think on it for a bit and I'll get back to you.

[MrHaila]

I spent a bit of time tinkering with TypeScript and Bun since I know that runtime better and got a structured output like this...

The latest SDK version is 2.4.0 and you are using 2.3.1. The generated types will be based on the 2.3.1 SDK.
[
  {
    name: "system.realloc",
    description: "Allocates heap space if ptr is NULL, else reallocates the given pointer. If size is zero, frees the given pointer.\n\nhttps://sdk.play.date/2.3.1/Inside%20Playdate%20with%20C.html#f-system.realloc",
  },
  {
    name: "system.error",
    description: "Calls the log function, outputting an error in red to the console, then pauses execution.\n\nhttps://sdk.play.date/2.3.1/Inside%20Playdate%20with%20C.html#f-system.error",
  },
  {
    name: "system.logToConsole",
    description: "Calls the log function.   Equivalent to print() in the Lua API.\n\nhttps://sdk.play.date/2.3.1/Inside%20Playdate%20with%20C.html#f-system.logToConsole",
  }
]

...that is pretty close to useful. I used the locally installed Playdate SDK as the source of truth as it ships with the latest docs HTML as well. I like this method as it will work offline, expect for the SDK version checking part that is kinda optional anyway.

The same intent could be expressed in many ways (and languages) but maybe something like this could be used to inject the doc comments? Easiest for maintenance would be to generate a commented copy of the source file so you know there is no junk left behind in the original, clean file after multiple runs. But maybe there are more clever ways? 🤔

Fun puzzle!

My code for reference: https://github.com/MrHaila/Zig-Playdate-Template/blob/doc-comments-scraper/doc-scraper/index.ts

Edit: I could imagine a GH action that every now and then checks for a new version and auto-generates the file with comments into a PR. Maybe even prints a diff. Could be an easy way to highlight any new functions or other changes in the C-api.

[DanB91]

I was also thinking of an offline approach would be best. Have some sort of program on my machine generate a new API zig file with the updated doc comments and then manually commit that back to the repo. Thank you for the code snippit! Will be super useful when writing this program.

I think I'll keep it manual initially, but perhaps if it gets too tedious I'll consider using a GH action.

I'll keep this issue open until I can make such a program and then commit the generated zig file back to the repo.

Thank you again for bringing this to my attention.