Godot: Add documentation to `--gdnative-generate-json-api` output

[nadako]

Godot version: 3.1

I am experimenting with Haxe/HashLink bindings for Godot again and I'm really pleased how simple it seems to be with GDNative. It is also great that the engine provides a nice JSON API specification with --gdnative-generate-json-api, good job!

Now onto the actual request, I would love that JSON output to also have documentation for classes/methods/etc. included, because then I can generate doc-comments for the Haxe type definitions that will later show up nicely in IDEs and API reference.

---

PS I see there's already godot_nativescript_set_class_documentation and friends for the types registered via GDNative. I assume that means that it'll show up when using the class in gdscript/visualscript? That's awesome!

[akien-mga]

CC @karroffel @neikeq

[karroffel]

I'm glad you like it! :)

Right now the "recommended" way to get documentation is to generate the XML file that Godot uses for the online documentation. That should contain all documentation.

This could be added to the JSON file as well, the only thing that speaks against that is that there is already an "official" way to generate the documentation, so this might be duplicated code that's error prone and needs more maintenance.

I would be in favor of adding it to the JSON file personally, that way binding authors have it easier to get that information.

---

The godot_nativescript_set_class_documentation etc don't do anything too fancy right now, they were mostly added for forward-compatibility.

You can already set docs and query them again, but GDScript/VisualScript etc do not make use of that yet unfortunately.

Maybe in future that will be added to the internal ScriptingLanguage/Script/ScriptInstance classes and the code editor can make use of it, but I don't think there has been work on that yet. :/

[nadako]

Right now the "recommended" way to get documentation is to generate the XML file that Godot uses for the online documentation. That should contain all documentation.

Well that works for me if it's machine-readable and I can query docs for all the things in the JSON output. Could you point me to some documentation (or code example) about this XML?

UPD: found it https://github.com/godotengine/godot/tree/master/doc/classes

[nadako]

So, I merged the two sources to generate some glue code and I like how it looks:

Although it would be nice not to parse XML and have everything in the JSON, but I can live with the current solution, so feel free to close this issue!

[Calinou]

Closing the issue per @nadako's request.