如何在GDscript中使用注释文档？提示不显示及参数注释写法问题

算力阿峰

2026-9-25

Godot GDScript 文档注释常见问题解答

注释不显示的核心原因

Godot 只有以##开头的双井号注释才会被识别为文档注释，普通单#注释仅用于代码内部备注，不会被编辑器识别为提示内容。
导出变量的正确写法示例：

## 角色最大移动速度，单位：像素/秒
export var max_speed: float = 200.0

文档注释的展示位置

「属性检查器」：鼠标悬停在对应导出变量的属性名上，注释会作为悬浮提示展示
「脚本编辑器自动补全」：输入变量、函数名称时，自动补全弹窗会附带对应的注释说明
「脚本悬停提示」：将鼠标放在脚本内的变量、函数名称上，会弹出包含注释的提示框
结构化导出：可以通过编辑器工具将所有文档注释统一导出为XML格式的项目文档

函数参数注释方法

Godot 支持通过@param标签对函数参数做注释说明，写法示例：

## 对目标造成固定值伤害
## @param target: 受击的目标节点
## @param damage_val: 要扣除的生命值数值
## @return 目标剩余的生命值
func deal_damage(target: Node2D, damage_val: int) -> int:
    target.hp -= damage_val
    return target.hp

注释完成后保存脚本，调用该函数时，参数输入提示、函数悬停提示中都会展示对应参数的说明内容。