Skip to content

Add doc comment tag for enum values #12513

Open
@Cykyrios

Description

@Cykyrios

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions