Skip to content

Conversation

@ColinSORourke
Copy link
Contributor

@ColinSORourke ColinSORourke commented Nov 29, 2025

Previously modules/gdscript/editor/gdscript_docgen.cpp would treat values of Named Enums identically to values of unnamed enums, and assign them all as ConstantDocs under MyClass.gd, using the values direct name as the ConstantDoc name.

// MyClass.gd
extends Node

## 1
enum {
	A = 0, ## 2
	B = 1, ## 3
}

## DocComment 4
enum NamedEnum {
	UP = 0, ## 5
	DOWN = 1, ## 6
}

## 7
enum OtherEnum {
	UP = 0, ## 8
	TOWN = 1, ## 9
	FUNK = 2, ## 10
}

Given the above code block, that would generate ConstantDoc mapping
MyClass.gd->class_docs.constants = {"A": 2, "B": 3, "UP": 5, "DOWN": 6, "UP":8, "TOWN":9, "FUNK":10}

Then, through the lookup chain, _lookup_symbol_from_base would tell the tooltip generator to look up the docs for this NamedEnum.UP under class_name "MyClass.gd".NamedEnum, symbol name "UP", causing a failure to retrieve any class docs.

This fix instead generates the unambiguous ConstantDoc mapping
MyClass.gd->class_docs.constants = {"A": 2, "B": 3, "NamedEnum.UP": 5, "NamedEnum.DOWN": 6, "OtherEnum.UP":8, "OtherEnum.TOWN":9, "OtherEnum.FUNK":10}
And also has _lookup_symbol_from_base return a more appropriate class_name and constant symbol.

@ColinSORourke ColinSORourke requested a review from a team as a code owner November 29, 2025 10:03
for (const GDP::EnumNode::Value &val : m_enum->values) {
DocData::ConstantDoc const_doc;
const_doc.name = val.identifier->name;
const_doc.name = String(name) + "." + String(val.identifier->name);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks incorrect. A constant name (identifier) ​​can't contain a period. At the very least, this is a hack, not a desirable option.

The main problem with proper enumeration support is that the core doc system doesn't properly support scoped enumerations. Instead, all enumeration elements are put into a common constant list. Native enumeration elements cannot be repeated, but custom enumerations can have elements with the same name in multiple enumerations.

Copy link
Contributor Author

@ColinSORourke ColinSORourke Nov 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR could be changed to just have lookup return the proper class_name, but not change anything about the symbol names, and it would at least start returning the correct DocString in most cases.

That of course would create the exact ambiguous behavior you're talking about, where MyClass.gd's ClassDoc can have multiple constants with duplicate names.

Is there an alternate Symbol scheme we could employ without the period?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we can currently do anything about this ambiguity on the GDScript side. Instead, we should first change the DocData structures and so on to properly support scoped enumerations.

@ColinSORourke
Copy link
Contributor Author

@dalexeev

Pushed an alternate solution that is more code, but employs the Enum Scope Searching already used by _get_property_help_data (which was behaving correctly even before this PR) and performs the same search in _get_constant_help_data

Does not change any of the DocData generation

@ColinSORourke

This comment was marked as outdated.

@ColinSORourke
Copy link
Contributor Author

Disregard previous comment! I gave this a little more thought and realized the existing routine could completely resolve ambiguity and be simpler without any other adjustments to DocGen. New push as of Nov.30th should be issue-free and correctly link Constants.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Enumeration Values' docstrings not shown on hover in Script Editor

2 participants