Add documentation page about gdextension_interface.json

[dsnopek]

This adds documentation on the gdextension_interface.json file that was added in PR godotengine/godot#107845

It attempts to address the remaining issues brought up on godotengine/godot#113732

cc @Bromeon

Fixes godotengine/godot#113732

[dsnopek]

This page needs a shorter title, because it gets weird line breaks currently:

Any suggestions? It could be "GDExtension interface JSON" maybe?

[Bromeon]

Great writeup, thanks a lot 👍 I especially like the examples after each section, they clarify a lot!

[Bromeon]

Any suggestions? It could be "GDExtension interface JSON" maybe?

In the future, there might be a section about the extension_api.json as well -- or even if not, it would probably be good to align on two official "prose" terms for these two files...

I'm not sure if "interface JSON" and "API JSON" are clear enough because the "I" in "API" is also "interface". Would a different term make sense here? In Rust I will likely keep using "header", which isn't very precise, but at least distinct enough for all practical purposes.

One defines the actual C interface (or FFI), while the other is more a specification/definition of concrete engine symbols (classes, enums, etc.)... Maybe some inspiration here?

[dsnopek]

@Bromeon Thanks! I attempted to integrate all of your suggestions in my latest push :-)

One defines the actual C interface (or FFI), while the other is more a specification/definition of concrete engine symbols (classes, enums, etc.)... Maybe some inspiration here?

Hm, yeah. The extension_api.json is really like a "ClassDB JSON" - it would have been nice if it were named something closer to that

When writing the note I added about extension_api.json in my latest push, I ended up using the words "low-level" and "high-level" to describe them. We could talk about the "Low-level GDExtension interface JSON" and "High-level extension API JSON"? The first word makes the big distinction, while still sort of including the file name in there, so people can find them?

[paddy-exe]

Small language nitpick. Otherwise this reads well. Great page addition!
As always thanks for including examples :)

[Bromeon]

Hm, yeah. The extension_api.json is really like a "ClassDB JSON" - it would have been nice if it were named something closer to that

When writing the note I added about extension_api.json in my latest push, I ended up using the words "low-level" and "high-level" to describe them. We could talk about the "Low-level GDExtension interface JSON" and "High-level extension API JSON"? The first word makes the big distinction, while still sort of including the file name in there, so people can find them?

I think it's a good start, but "high vs. low" is still very abstract... All of "ClassDB API", "classes API", "class specification", "class definitions" would be more concrete -- do you not think something along that would be possible? Without renaming the file now, of course. But high/low isn't reflected in the filename, either...

The C API could still be "low-level interface", "C interface", "FFI interface" etc. Something that distinguishes the technical interface from the API JSON, which is more a specification or type database.

But I don't know, naming is hard 😅

[Ivorforce]

Looks good to me, I've got only nitpicks!

[dsnopek]

The C API could still be "low-level interface", "C interface", "FFI interface" etc. Something that distinguishes the technical interface from the API JSON, which is more a specification or type database.

In my latest push, I've gone for "C interface" such that the sidebar looks like this:

So, now at least it fits! Hopefully, "C interface" is clear enough. Naming is hard and I feel about equally unsure about every option :-)

[Bromeon]

Looks really good! I only have a few remarks left, and they're bordering nitpicking territory 🙂

[Bromeon]

This is more a question about the format:

It will always be given, and use void as the type if the function returns no value.

Is there a good reason to deviate from extension_api.json here, which omits the return_value key for void return types? Notably, the key is called "return value", not "return type" 🤔

[dsnopek]

Hm, well, the implementation was easier :-)

We already have "void" as a valid type (so that we can have "void *" and other modifiers) and simply always requiring this is simpler than having to check if it exists

I can look at what it would take to change the parsers. We'd then have to decide if we want to disallow explicitly specifying a return type of "void" (and force it to be omitted in that case), which would need to be reflected in the parsers and the schema

[dsnopek]

Here's a PR that changes the format to omit the return_value for void functions: godotengine/godot#114684

[akien-mga]

Thanks!