feature: godot docs annotations for LuaLS by howhow2315 · Pull Request #237 · gilzoide/lua-gdextension

howhow2315 · 2026-05-30T23:50:54Z

Goal

Improve Lua language support for Godot by integrating official engine XML documentation and upgrading annotation definitions used by LuaLS, making engine APIs faster, and easier to work with in the editor.

Changes

Added Godot engine submodule containing XML documentation for annotations
Updated LuaLS annotation definitions to include Godot XML docs annotations
Separated manual definitions into their own files in a subdirectory for clarity and maintainability
Switched sol2 dependency to the official upstream repository
Grouped submodules in .gitmodules by subsystem for better structure
Renamed and reorganized submodules to match repository path naming conventions
Performed small diagnostics cleanup and general organization improvements

…om the godot engines xml docs

howhow2315 · 2026-05-30T23:59:10Z

hey there @gilzoide this is my first PR and i apologize if i broke any rules!
i had made a post about this on bluesky a while ago but got hit by life like a train, and things finally settled down

there were a few things that would be good alongside this like including the .po translation support that godot itself does so people can clone/fork it and build their preferred language, or include plugins to translate it which would require a tiny major refactor

you had included a json_types.py for your original structure to go alongside extension_api.json and while it could be helpful i think that with adding the docs it becomes convoluted so i left it out

only thing of warning is that tools/code_generation/generate_lua_godot_api.py/parse_godot_class_xml is primarily AI generated (the rest was me offline over weeks)

i also noticed that the source of sol2 was the wrong one which was interesting but i included that in this patch alongside some formatting stuff for the other submodules since i was adding a new one (godotengine)

and finally i think the next step is adding script_templates! ive already finished that feature as well and will open another PR for this momentarily!

this goes without saying but feel free to critique or do whatever you want with this, thank you for the baseline for all of this to be possible

howhow2315 · 2026-06-10T03:00:45Z

there are some mistakes inside the manual definitions, i unfortunately forgot to review them as i cherry-picked them from one of my personal versions where i was testing making export a metatable with a __call function. will fix this soon

howhow2315 · 2026-06-10T03:04:01Z

typedarray::RID?
some typed arrays are also not being clocked right

gilzoide

Hey @howhow2315, thanks a lot for the contribution! This is a really good idea, making docs in LuaLS much more detailed. Overall, the changes look solid, I have commented some stuff that I found out.

And again, sorry for taking so long to review this, you know how life can be. This PR seemed (and is) quite bigger than the other, that's why I reviewed that one first.

One thing that bothers me is the order of @param and @return in the new docs, almost everywhere I see API docs the brief and long descriptions come first, while this kind of metadata goes last. Why do the opposite?

Another thing, about we using a fork of sol2, it's because the fork fixed a memory leak when indexing metatypes with numbers (see #156). I see in the final diff that it has been changed back, so just keep it like that.

gilzoide · 2026-07-10T13:11:25Z

Why did you pick a "random" commit from tree-sitter instead of a commit tagged as a stable release?

when i went through and made formatted the submodules i must have messed up!!! half of them had a mismatched naming convention, some being lib/*, and some just being *
my fault !!

gilzoide · 2026-07-10T13:34:37Z

+BRANCH = "master"
+# BRANCH = "4.6"


This is never used and likely doesn't need to exist here.

yeah i agree completely just something i had in mind while i started writing

gilzoide · 2026-07-10T13:38:20Z

I see this script generates definitions for classes/@GDScript.lua. These are GDScript only and are not available in Lua, we should filter them out. Lua defines most of them via the utility functions, while some are built-in (such as await).

youre completely correct, since that file is extremely long just like @GlobalScope i was using it to test things, i should have removed it

gilzoide · 2026-07-10T13:40:28Z

+    None: "nil",
+    "inf": "math.huge()",
+    "[]": "{}", # the value ends up as just "[]", this would be an ordered table yes? we should probably just use a table
+    "nan": "0/0", # adding a math.NAN would probably be a good idea


adding a math.NAN would probably be a good idea

In Lua? Lua doesn't define NaN and lets one generate one easily (such as with 0/0), I don't think we need to bother.

gilzoide · 2026-07-10T13:44:26Z

        [
            "tools/code_generation/generate_lua_godot_api.py",
            "lib/godot-cpp/gdextension/extension_api.json",
        ],


Now that this script also reads lib/godot/... we might want to add at least one dependency here to rebuild the docs in case the commit for lib/godot changes. Also add doc_classes from Lua GDExtension, since it is also used by the script.

gilzoide · 2026-07-10T13:51:11Z

+
+    return text
+
+def parse_godot_class_xml(xml) -> Dict[str, Any]:


I'm getting a NameError: name 'Dict' is not defined. Did you mean: 'dict'? error here. Python 3.13.9 on a macOS, installed from pyenv.
You should either use dict or import Dict from typing.

i think i removed my Dict import by accident in my last cleanup and i didnt catch it because of my venv

gilzoide · 2026-07-10T13:54:07Z

+            "addons/lua-gdextension/lua_api_definitions/variants",
+            "addons/lua-gdextension/lua_api_definitions/enums",
+            "addons/lua-gdextension/lua_api_definitions/functions",
+            "addons/lua-gdextension/lua_api_definitions/classes"


Now that the generated files changed, you should add these new folders to .gitignore.

i swore i did a catch all with "addons/lua-gdextension/lua_api_definitions/*" and "!addons/lua-gdextension/lua_api_definitions/manual",

gilzoide · 2026-07-10T13:56:42Z

+    # i believe the docs include something like "**Deprecated: This is the reason why and or what to use instead"
+
+    # i assume we should express methods with `:` instead of `.`
+    # im pretty sure lua-gdextension forces use of : no matter what, but how does it work with static methods?


Static methods are also forced to use :. Maybe they shouldn't, we can discuss that, but right now they are.

gilzoide · 2026-07-10T14:02:57Z

In the Variants side, this script generates definitions for Nil, which doesn't exist in Lua

Constructors for Variants use the call syntax instead of :new: Vector2(1, 2)

yeah im 100% sure i thought about both of those things and went "ill just add it in case" 😭

gilzoide · 2026-07-10T14:14:01Z

+    # as well as for the value and type instead of manually in each spot its required
+
+    # TODO
+    # deprecated


There could be a [deprecated] tag in the same place as [static] and [const].

howhow2315 and others added 8 commits May 30, 2026 18:12

added godot engine submodule for xml docs for annotations

7ebcdcd

rename submodules to match path naming

8309961

switch sol2 to official repository

b8ba6a5

group submodules in .gitmodules by subsystem

ec9e9a6

separated manual definitions from one file

98dbfa3

small diagnostics cleanup & organization

62241bd

cleanup & organization to match changes

3c7999f

feature: upgraded godot_lua_api definitions to include annotations fr…

6ae0c21

…om the godot engines xml docs

gilzoide reviewed Jul 10, 2026

View reviewed changes


		return text

		def parse_godot_class_xml(xml) -> Dict[str, Any]:

Uh oh!

Conversation

howhow2315 commented May 30, 2026

Goal

Changes

Uh oh!

howhow2315 commented May 30, 2026

Uh oh!

howhow2315 commented Jun 10, 2026

Uh oh!

howhow2315 commented Jun 10, 2026

Uh oh!

gilzoide left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

howhow2315 Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

howhow2315 Jul 19, 2026 •

edited

Loading