JSDoc Script Comments


If you wish your custom scripts to have code completion and to show the required arguments etc... in the script editor, then you need to add some JSDoc style comments. If you have imported a project created with a previous version of GameMaker Studio, then you may have seen comments like this at the top of the compatibility script for the function: JSDoc Import Example

The format for a typical script header would be to have the description of the function, the function name and then list the different arguments (parameters) that the function takes, making sure to start each line with a triple backslash "///" as that tells GameMaker Studio 2 to parse comment as JSDoc. The comments themselves need to be given an identifier (preceded by "@") and content, and the available identifiers are as follows:

Identifier Content
@function / @func The full script name and arguments for the function, "my_script(x, y, colour)".
@description / @desc A general description of what the script does.
@param / @arg / @argument The argument type (optional), enclosed in {}, the argument name, and a short description (with a space in between)

To get an idea of how this would work when writing your own scripts, let's take this basic example:

// is_same_object(id, object)
if argument0.object_index == argument1
   {
   return true;
   }
else return false;

All this script does is check to see if an instance has the same object_index as a given object and would be called simply as:

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

However, writing that into the script editor wouldn't show you the arguments nor give you any help when using it, so we need to add in a description, a function name, and the arguments as JSDoc comments like this:

/// @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;

Now, when calling this script in code anywhere, you will get auto-complete and argument help etc... JSDoc Example

In the image above, the top part shows the function in the auto-complete and the bottom part shows how the argument helper at the bottom works. It's important to note that when you use the @function identifier, then the script name that you give there will show in the IDE just the same as the script name in the resource tree. So, you can name the script one thing in the resource tree and name it as another using @function and the IDE will recognise both as alias of the same script resource, but only the @function one will have auto-complete, etc...

Note that both the optional "type" and the obligatory "description" parts of @param are not displayed by default in the IDE code complete, and to see them you must activate the options in the GML Preferences.