JSDoc Script Commentaires


Si vous souhaitez que vos scripts personnalisés soient complétés et que les arguments requis soient affichés dans l'éditeur de script, vous devez ajouter des commentaires de style JSDoc. Si vous avez importé un projet créé avec une version précédente de GameMaker Studio, vous avez peut-être vu des commentaires de ce type en haut du script de compatibilité de la fonction: Exemple d'importation JSDoc

Le format d'un en-tête de script typique serait d'avoir la description de la fonction, le nom de la fonction, puis de lister les différents arguments (paramètres) que prend la fonction, en commençant par chaque ligne avec une triple barre oblique inversée "///" cela indique à GameMaker Studio 2 d'analyser le commentaire en tant que JSDoc. Les commentaires eux-mêmes doivent recevoir un identifiant (précédé de "@") et du contenu, et les identifiants disponibles sont les suivants:

Identifiant Contenu
@fonction / @func Le nom complet du script et les arguments de la fonction " my_script(x, y, colour) ".
@description / @desc Une description générale de ce que fait le script.
@param / @arg / @argument L'argument type (optionnel), entouré de {}, le nom de l'argument, et une courte description (avec un espace entre les deux)

Pour avoir une idée de la façon dont cela fonctionnerait lors de l'écriture de vos propres scripts, prenons cet exemple basique:

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

Tout ce script fait est de vérifier si une instance a le même object_index qu'un objet donné et serait appelée simplement comme:

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

Cependant, écrire cela dans l'éditeur de script ne vous montrerait pas les arguments et ne vous donnerait aucune aide lors de son utilisation, nous avons donc besoin d'ajouter une description, un nom de fonction, et les arguments comme des commentaires JSDoc comme ceci:

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

Maintenant, lorsque vous appelez ce script en code n'importe où, vous obtiendrez l'auto-complétion et l'aide aux arguments etc... Exemple JSDoc

Dans l'image ci-dessus, la partie supérieure montre la fonction dans l'auto-complétion et la partie inférieure montre comment fonctionne l'argument auxiliaire en bas. Il est important de noter que lorsque vous utilisez le @function Identifiant, le nom du script que vous indiquez s'affichera dans l'EDI exactement comme le nom du script dans l'arborescence des ressources. Ainsi, vous pouvez nommer le script une chose dans l'arbre des ressources et le nommer comme un autre en utilisant @function et l'IDE reconnaîtra à la fois comme alias de la même ressource de script, mais seulement @function on aura auto-complète, etc...

Notez qu'à la fois le "type" optionnel et les parties "description" obligatoires @param ne sont pas affichés par défaut dans le code IDE complet, et pour les voir vous devez activer les options dans les Préférences GML.