GMS2中JSDoc注释的使用

Posted 2021-04-30 GMS手札

本文是官方文档JSDoc的说明

---

如果你希望自定义脚本具有代码自动补全并可以在脚本编辑器中自动提示所需的参数等，就需要添加一些JSDoc格式的脚本注释。如果你导入了老版本的项目，则可能在一些淘汰的函数上方见过这样的内容

一个标准的脚本头文件注释的格式应该包含函数的描述、函数名，并列出该函数所需要的不同参数，务必保证每一行的开头是三个反斜杠“///”，这会告知GMS2此处应注释为JSDoc格式。不同的内容前还应给予标识符（以@开头），标识符格式如下

标识符	含义
@function / @func	完整的函数名及传参格式，如："my_script(x, y, colour)".
@description / @desc	对当前函数功能的大致描述
@param / @arg / @argument	以"{}"包围的参数类型(可选),参数名称及简短的描述（以空格间隔）

要具体了解使用的方法，我们以下面这个例子来进行说明：

if argument0.object_index == argument1
   {
   return true;
   }else return false;

上面这个脚本的工作就是检查一个实例是否与传入的对象的object_index一致，我们像下面这样来调用这个脚本函数:

if is_same_object(id, obj_Player)
   {
   instance_destroy()
   }

但是现在这样写进脚本里，当你调用的时候编辑器无法给你提供自动补全以及参数提示，因此我们需要添加一个JSDoc的注释，如下所示：

/// @function is_same_object(id, object)
/// @description Compare an instance object index with that of another.
/// @param {real} instance_id The unique instance ID value of the instance to check.
/// @param {real} object_index The object index to be checked against.if argument0.object_index == argument1
   {
   return true;
   }
else return false;

现在，无论我们在何处调用这个脚本时，都会看到如下的自动补全和参数提示了。

在上面这个图片中，第一张图显示了代码自动补全的功能，第二张图则显示了编辑器底部的参数助手是如何运作的。要注意，当你使用"@function"标识符时，在IDE中会提示与资源树中脚本名称一致的名称，因此你可以在资源树中把脚本命名为A，然后在@function中定义成B，IDE会自动把两者判断为同一个脚本的不同别名，但是只有@function定义的名称具有自动补全功能

我个人测试@function好像没啥用，只要定义了@param以后就会有自动补全和参数提示了，自动补全的函数名就是脚本名称，@function中我定义了另一个名字并没有在自动补全中出现，如果有朋友成功了可以告知

注于2018/01/24

另外要注意，默认情况下，在这里定义的@param的参数类型以及描述都不会在状态栏中显示出来，如有需要则去设置项中单独设置