Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add built-in GDScript keywords to the class reference #97196

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

Calinou
Copy link
Member

@Calinou Calinou commented Sep 19, 2024

These are part of @GDScript and appear in search results as part of a new builtin documentable type. (keyword is not used, as keywords is already the name of an optional attribute for most documentable types.)

Keywords can now be Ctrl + clicked in the script editor to go to their class reference description.

Preview

gdscript_ctrl_click_keyword.mp4

TODO

  • Fill in descriptions.
  • Define parameters for keywords when relevant.
  • Update doc_status.py to allow tracking progress on builtins.
  • Test make_rst.py's reStructuredText generation on the docs website.

Filling in the descriptions could be done in a separate PR if we want, like we did for #48548 (where #63870 added the descriptions).

In a future PR, we can look into using a similar approach to document shader keywords in the class reference, in addition to built-ins (which would probably be considered member variables there).

@Mickeon
Copy link
Contributor

Mickeon commented Sep 20, 2024

I know it's the easiest way to accomplish this, but something about it... It doesn't feel right for builtins to be something that can be documented for every single class, even though they're GDScript-exclusive concepts.

Furthermore, because only keywords are documented, the class reference still lacks a general point of reference for literals, operators, or similar. This may be fine, and for the most part we can direct users to the GDScript reference, but it still means that adding just keywords doesn't accomplish the goal of an all-encompassing guide built right inside the editor.

@HolonProduction
Copy link
Member

HolonProduction commented Sep 20, 2024

So I just did a small bit of coding using this, and I'm not a fan of the Ctrl+Click lookup on keywords. In my opinion it adds too much noise when trying to lookup other stuff. Since keywords (especially var) might be on the screen in high amounts (10+) just moving the cursor to something I want to lookup will cause a lot of flickering underlines all over the screen.

It might be helpful for beginners, but knowing GDScript it feels more like a downgrade of the script editor to me.

Maybe we could prevent the underline highlighting for certain lookup targets 🤔

Edit: Or given that no one will lookup the same keyword that often it might be better to limit the lookup on them to the context menu.

These are part of `@GDScript` and appear in search results as part of
a new `builtin` documentable type. (`keyword` is not used, as `keywords`
is already the name of an optional attribute for most documentable types.)

Keywords can now be Ctrl + clicked in the script editor to go to their
class reference description.
@aXu-AP
Copy link
Contributor

aXu-AP commented Sep 20, 2024

I remember when starting writing gdscript I had to check a good few times what was the syntax for for and match before getting it memorized. Under context menu it could go unnoticed, in that case it might as well not exist.

@Mickeon
Copy link
Contributor

Mickeon commented Sep 20, 2024

So I just did a small bit of coding using this, and I'm not a fan of the Ctrl+Click lookup on keywords. In my opinion it adds too much noise when trying to lookup other stuff.

I think the "noise" can be severely mitigated and the existing behaviour should no longer be an issue. When hovering over keywords, not all occurrences of that keyword should be highlighted.
Keywords are not class members, variables, or similar. For those, in layman's terms, the same name means the same reference. As "stupid" as it sounds, two for in a code block are two entirely different instances.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants