PRD: Add enum container lookups for global enums

[deevus]

Problem Statement

Godot global enums such as JoyButton are present in the upstream API data, and their values are already represented in XML docs as enum-qualified constants under @GlobalScope. However, gdoc does not currently generate a documentation entry for the enum container itself. Users can reasonably expect gdoc JoyButton and gdoc @GlobalScope.JoyButton to show the JoyButton enum and its values, but today those symbols are missing.

This makes enum discovery harder and creates an inconsistent lookup model: enum values can exist conceptually, while the enum that contains them cannot be looked up directly.

Solution

Add enum container entries to the documentation model and cache generation flow. For global enums, generate both the fully-qualified symbol and a short top-level alias, so users can run either gdoc JoyButton or gdoc @GlobalScope.JoyButton. The enum page should list the enum's values, including names, numeric values, and descriptions when available.

Existing enum value lookup behavior should remain compatible. The feature should fit into the current XML-doc pipeline rather than introducing a separate extension API parsing path.

User Stories

1. As a Godot developer, I want to run gdoc JoyButton, so that I can quickly inspect controller button constants without opening browser documentation.
2. As a Godot developer, I want to run gdoc @GlobalScope.JoyButton, so that I can use the fully-qualified symbol name when I know the enum lives in global scope.
3. As a Godot developer, I want enum documentation to list all values, so that I can discover valid constants from the enum page.
4. As a Godot developer, I want enum values to include their numeric values, so that I can compare them with input events, saved data, or API return values.
5. As a Godot developer, I want enum values to include descriptions, so that I can understand platform-specific meanings such as controller button naming conventions.
6. As a Godot developer, I want existing enum value lookups to keep working, so that current workflows are not broken by the new enum container support.
7. As a Godot developer, I want global enum aliases to behave consistently with global functions, so that common symbols can be looked up without always typing @GlobalScope.
8. As a Godot developer, I want fully-qualified enum names to remain available, so that ambiguous or documented names can still be addressed precisely.
9. As a terminal-first user, I want enum pages to render cleanly in terminal and markdown output, so that they remain readable in both interactive and piped workflows.
10. As a maintainer, I want enum support to reuse the existing XML-doc cache pipeline, so that cache generation remains predictable and version-matched to the installed Godot version.
11. As a maintainer, I want enum entries to be modeled explicitly, so that future enum improvements have a clear representation instead of relying on ad hoc aliases.
12. As a maintainer, I want tests covering enum database generation and markdown rendering, so that regressions are caught when parser or cache behavior changes.
13. As a maintainer, I want tests covering both short and fully-qualified global enum lookups, so that the expected user-facing behavior is locked in.
14. As a maintainer, I want class-scoped enum grouping to remain possible, so that the model can support enums such as Node.ProcessMode without conflating them with global aliases.
15. As a maintainer, I want duplicate or overloaded symbol behavior to be deterministic, so that aliases do not unexpectedly replace unrelated entries.

Implementation Decisions

• Add an explicit enum container concept to the documentation database model.
• Generate enum container entries from constants that include an enum qualifier.
• For constants under global scope, create a fully-qualified enum symbol and a short top-level alias.
• Preserve individual enum value entries and associate them with the generated enum container.
• Render enum container documentation as a normal documentation entry with a dedicated values listing.
• Keep the implementation based on the current XML documentation source rather than parsing the extension API JSON for this feature.
• Treat JoyButton as an alias of @GlobalScope.JoyButton rather than a separate independent enum.
• Avoid broad unrelated lookup or search work; this PRD is only about direct enum symbol generation and rendering.
• Maintain existing global function precedence behavior and avoid introducing unexpected overwrites for non-enum symbols.

Testing Decisions

• Add tests for XML-to-database enum grouping to verify enum containers are generated from enum-qualified constants.
• Add tests for global enum aliasing to verify both the fully-qualified name and short name resolve.
• Add tests for markdown output to verify enum pages list their values, numeric defaults, and descriptions.
• Add cache generation/readback tests to verify enum container entries are written and can be read through the normal lookup path.
• Add regression coverage ensuring existing enum value entries still exist after enum container generation.
• Prefer behavior-focused tests over implementation-detail tests: assertions should verify public lookup results and rendered documentation, not private intermediate data structures except where the database API is already the unit under test.
• Use the existing snapshot-style markdown tests where appropriate, adding focused snapshots for enum pages.
• Include tests for both JoyButton and @GlobalScope.JoyButton behavior.

Out of Scope

• Full-text search for enums or enum values.
• Parsing extension_api.json as a new documentation source.
• Support for annotations, theme items, or other API element categories not already part of this enum feature.
• Changing how Godot XML docs are fetched.
• Redesigning cache layout beyond what is necessary to store and read enum entries.
• Resolving all possible symbol ambiguity cases beyond deterministic handling for global enum aliases.

Further Notes

The immediate motivating example is JoyButton, which should be available through both gdoc JoyButton and gdoc @GlobalScope.JoyButton. The design should generalize to other global enums exposed through @GlobalScope enum-qualified constants.