Skip to content

Bug: Godot documentation cross-references to autoload enums fail from other script files #12

Description

@edzillion

Problem Description

Cross-references to enums defined in autoload scripts don't work when referenced from other script files within the same addon using Godot's built-in documentation system.

Specific Issue

In helper_functions.gd, attempting to create documentation links to StatMath.SupportedDistributions enum (defined in the StatMath autoload) results in:

  • Links that appear clickable but lead to blank pages
  • Links that don't navigate anywhere when clicked

Steps Attempted

We tried multiple cross-reference syntaxes as documented in Godot's documentation system:

  1. [enum StatMath.SupportedDistributions] - Creates link that goes to blank page
  2. [enum SupportedDistributions] - Creates link that does nothing when clicked
  3. [member StatMath.SupportedDistributions] - Creates link that goes to blank page
  4. [constant StatMath.SupportedDistributions] - Creates link that goes to blank page

Current Workaround

Reverted to using [code]StatMath.SupportedDistributions[/code] which provides proper formatting without broken links.

Expected Behavior

Cross-references should properly link to the enum definition in the StatMath autoload and navigate correctly when clicked.

Environment

  • Godot Version: 4.4
  • Project Type: GDScript addon
  • Autoload Setup: StatMath registered as autoload pointing to res://addons/godot-stat-math/stat_math.gd

Additional Context

  • The enum is properly documented with ## comments in the StatMath autoload
  • The autoload is correctly registered in project.godot
  • Cross-references work fine for built-in Godot types (e.g., [enum MouseButton])
  • Issue appears specific to enums in custom autoload scripts

Code References

Enum definition (stat_math.gd):

## Supported statistical distributions for various calculations
enum SupportedDistributions {
    NORMAL,     ## Normal (Gaussian) distribution  
    STUDENT_T,  ## Student's t-distribution
    CHI_SQUARED ## Chi-squared distribution
}

Failed cross-reference (helper_functions.gd):

## Converts a string distribution name to [code]StatMath.SupportedDistributions[/code] enum.
static func string_to_distribution_enum(distribution: String) -> StatMath.SupportedDistributions:

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions