Description
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:
- This is an issue with the in-editor help
- The possible name conflicts cannot be resolved automatically