Skip to content

Add doc comment tag for enum values #12513

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

Open
Cykyrios opened this issue May 28, 2025 · 1 comment
Open

Add doc comment tag for enum values #12513

Cykyrios opened this issue May 28, 2025 · 1 comment

Comments

@Cykyrios
Copy link

Cykyrios commented May 28, 2025

Describe the project you are working on

An online documentation generator, but this applies to in-editor help as well.

Describe the problem or limitation you are having in your project

Doc comments allow references to enums with [enum MyEnum] or [enum MyClass.MyEnum], and constants with [constant CONSTANT] or [constant MyClass.CONSTANT], but enum values cannot be referenced properly, as [constant MyEnum.VALUE] does format the text in the in-editor help, but doesn't actually link anywhere (see third point in godotengine/godot#106828).

Moreover, even if this were fixed, there would still be a possible issue with conflicting names: if you have a Flag enum in a class, and a separate Flag class, what does [constant Flag.SOMETHING] refer to? A value in the Flag enum of the current class, or a constant in the Flag class?

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Add a new doc comment tag for enum values, e.g. [enum_value Enum.VALUE], or maybe the shorter [value Enum.VALUE], and if links to individual values are not handled, link to the enum itself instead.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

In the following script:

enum MyEnum {FIRST_VALUE, SECOND_VALUE}

## See [value MyEnum.FIRST_VALUE] for details.
var my_var := MyEnum.FIRST_VALUE

The doc comment would link to FIRST_VALUE in the in-editor documentation, or to the MyEnum enum itself.

If this enhancement will not be used often, can it be worked around with a few lines of script?

It cannot be worked around, as this is an issue with the in-editor documentation. For my own tool though, a possible workaround would be to search for the enum in the current class, then constants in other classes, but that wouldn't solve the possible naming conflict.

Is there a reason why this should be core and not an add-on in the asset library?

I see 2 reasons:

  1. This is an issue with the in-editor help
  2. The possible name conflicts cannot be resolved automatically
@Cykyrios
Copy link
Author

As I was "fixing" some broken references in my documentation, I actually noticed something I was not expecting: for an enum named MyEnum in class MyClass, a comment such as [constant MyClass.MyEnum.VALUE] does not link anywhere, as noted above, but [constant MyClass.VALUE] does link to the proper enum value; however, this leads to a new problem: if 2 enums have a value with the same name, how is the link resolved? The only way to avoid ambiguity here would be to prefix the enum name in the value itself, which kind of defeats the point of having named enums.

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

No branches or pull requests

2 participants