JS Doc dla Feather (GMS 2022.2+)
Wtorek, 25 Stycznia 2022, 23:35
Czas czytania 2 minuty, 8 sekund
Zgodne z GM:
Opis parametrów możliwych do użycia z JS Doc w Feather.
GMS 2 2022.2+ zawierać będzie nowy system podpowiadania składni, który uwzględniać ma np. zwracane typy zmiennych, czy podpowiadanie właściwości struktur i konstruktorów.
Czasem jednak takie zmienne trzeba będzie podowiedzieć, lub możemy też potrzebować je wymusić, dlatego wraz z postępami prac nad tą nowością w programie postaram się tutaj przygotować pełną listę przykładów jak tego użyć.
Na luty 2022 znamy taką listę parametrów:
kod// typy zmiennych:
Undefined
String
Real
Bool
Array
Pointer
Function
Struct // dla dowolnych struktur
Struct.CarType // dla konstruktorów, np. function CarType(name) constructor {}
Id // więcej info niżej
Resource
Constant
ArgumentIdentity
Mixed
Id jest specjalnym typem, który może posłużyć to tworzenia własnych typów, np. żeby dane zwrócone z jakiejś funkcji, bez względu na typ, mogły być użyte w innej funkcji, np. poniżej tworzymy typ Id.Wow:
kod/// @returns {Id.Wow}
function wow_create() {
static id = 0;
return id++;
}
/// @param {Id.Wow} _wow
/// @param {real} _value
function wow_amazing(_wow, _value) {
// ...
}
var _w = wow_create(); // zwrócona zostaje liczba (real), ale Feather uzna ten typ za Id.Wow
wow_amazing(_w, 15); // wszystko jest ok, bo pierwszy argument jest typu Id.Wow
wow_amazing(10, 15); // pojawi się błąd, gdyż real to nie Id.Wow
kod/// @desc Opis
// alternatywnie:
/// @description Opis
kod/// @param {typ} nazwa_zmiennej Opis
// Można też użyć: @paramter, @arg, @argument
kod// Do ignorowania i nie podpowiadania niektórych funkcji można użyć:
/// @ignore
kod// z kolei do funkcji, które chcemy wkrótce usunąć z gry, można użyć
/// @deprecated
kod// wymuszanie typu zmiennej, np. gdy wiemy, że inny obiekt/skrypt ustawi własnie taki typ
/// @context {FUNCTION_NAME lub OBJECT_NAME lub CTOR_FUNCTION_NAME}
kod// opisanie jaki typ zwraca funkcja, co pomoże ograniczać @context
/// @returns {type}
kod/**
* możliwe są też
* wieloliniowe opisy
* @param {string} name
* i dalszy opis!
* ...
*/
Ctrl+Q - pokazuje menu Quick Fix, które pozwala w niektórych przypadkach automatycznie poprawić kod. W pozostałych, pozwala np. na oznaczenie za pomocą specjalnego komentarza, że mamy ignorować jakiś błąd.
Ignorować Feather potrafi na dwa sposoby - cały kod (skrypt, event), lub tylko następujące po nim wyrażenie.
Cały kod ignoruje się poprzez dodanie:
kod// Feather disable GMXXXXlub wsystkie błędy poprzez:
kod// Feather disable allnatomiast jedno wyrażenie:
kod// Feather disable once GMXXXXgdzie GMXXXX to numer błedu, np. GM1001. Tak, ten komentarz używa dwóch zamiast trzech slashy, dla odróżnienia od JSDoc.
Czasem jednak takie zmienne trzeba będzie podowiedzieć, lub możemy też potrzebować je wymusić, dlatego wraz z postępami prac nad tą nowością w programie postaram się tutaj przygotować pełną listę przykładów jak tego użyć.
Na luty 2022 znamy taką listę parametrów:
kod// typy zmiennych:
Undefined
String
Real
Bool
Array
Pointer
Function
Struct // dla dowolnych struktur
Struct.CarType // dla konstruktorów, np. function CarType(name) constructor {}
Id // więcej info niżej
Resource
Constant
ArgumentIdentity
Mixed
Id jest specjalnym typem, który może posłużyć to tworzenia własnych typów, np. żeby dane zwrócone z jakiejś funkcji, bez względu na typ, mogły być użyte w innej funkcji, np. poniżej tworzymy typ Id.Wow:
kod/// @returns {Id.Wow}
function wow_create() {
static id = 0;
return id++;
}
/// @param {Id.Wow} _wow
/// @param {real} _value
function wow_amazing(_wow, _value) {
// ...
}
var _w = wow_create(); // zwrócona zostaje liczba (real), ale Feather uzna ten typ za Id.Wow
wow_amazing(_w, 15); // wszystko jest ok, bo pierwszy argument jest typu Id.Wow
wow_amazing(10, 15); // pojawi się błąd, gdyż real to nie Id.Wow
kod/// @desc Opis
// alternatywnie:
/// @description Opis
kod/// @param {typ} nazwa_zmiennej Opis
// Można też użyć: @paramter, @arg, @argument
kod// Do ignorowania i nie podpowiadania niektórych funkcji można użyć:
/// @ignore
kod// z kolei do funkcji, które chcemy wkrótce usunąć z gry, można użyć
/// @deprecated
kod// wymuszanie typu zmiennej, np. gdy wiemy, że inny obiekt/skrypt ustawi własnie taki typ
/// @context {FUNCTION_NAME lub OBJECT_NAME lub CTOR_FUNCTION_NAME}
kod// opisanie jaki typ zwraca funkcja, co pomoże ograniczać @context
/// @returns {type}
kod/**
* możliwe są też
* wieloliniowe opisy
* @param {string} name
* i dalszy opis!
* ...
*/
Ctrl+Q - pokazuje menu Quick Fix, które pozwala w niektórych przypadkach automatycznie poprawić kod. W pozostałych, pozwala np. na oznaczenie za pomocą specjalnego komentarza, że mamy ignorować jakiś błąd.
Ignorować Feather potrafi na dwa sposoby - cały kod (skrypt, event), lub tylko następujące po nim wyrażenie.
Cały kod ignoruje się poprzez dodanie:
kod// Feather disable GMXXXXlub wsystkie błędy poprzez:
kod// Feather disable allnatomiast jedno wyrażenie:
kod// Feather disable once GMXXXXgdzie GMXXXX to numer błedu, np. GM1001. Tak, ten komentarz używa dwóch zamiast trzech slashy, dla odróżnienia od JSDoc.
