JSDoc documentation / sample usage demo on how to correctly document structs

[TeunK]

Is there any example / doc that shows typical usage of the JSDoc features supported by Stitch?
I find that one of GM's biggest caveats is missing typing, and Stitch is showing huge potential for resolving this.

However currently I'm trying to find a way to document the fields of a struct but am unable to find how ( / if?) it can be done.
The doc describes that Stitch will by default infer the first-definition as the type. But this won't work when the keys of the struct are defined through accessors, or when the struct is a function input parameter.

Eg. in situations:

function doSomething(config: {x0: Real, y0: Real}) { ... }
or

resources = {}; // Stitch will only see it being a Struct, but won't know what the fields it is going to contain
resources[$ ResourceTypes.Water] = { name: "Water", icon: spr_Water};

In fact, for the above, is it possible to specify the key type as well?
eg. resources: { readonly [key: Enum.ResourceTypes]: { name: string, icon: Sprite} } = {}

Made some attempts but neither seem to work:

/// @param {Struct} config
/// @param {Real} config.x0
function doSomething(config) {...}

// alternatively
/// @param {Struct { x0: Real, y0: Real }} config
function doSomething(config) {...}

[adam-coster]

Stitch doesn't support Typescript-style type annotations -- it's still mostly just the kind of thing that Feather does, and uses Feather type-name conventions. Since Feather doesn't have a way to provide a struct type without actually having the struct, neither does Stitch (currently). It's something I'd like to start supporting eventually, since it's pretty cumbersome to create structs just to use as types.

What we currently do is just create constructors to model types. We figure that they'll get pruned during compile since they aren't used.

For example:

function Config() constructor {
  x0: 0; // To get the inferred type "Real"

  // Or use Stitch-specific JSDoc variable-declaration comments
  /// @instancevar {Real} x1
}

Then you'd reference that constructor as a type elsewhere:

/// @param {Struct.Config} config
function doSomething(config) {...}

Stitch does try to update struct types as it sees variables get added to them, but the parser only evaluates string literals as keys.

resources = {};
resources[$ ResourceTypes.Water] = { name: "Water", icon: spr_Water}; // ❌ Stitch doesn't know what to do with ResourceTypes.Water
resources[$ "water"] = { name: "Water", icon: spr_Water}; // ✅ Stitch *should* update the type for 'resources' to include the field "water", with the inferred type based on the literal struct value you set it to

For your case resources: { readonly [key: Enum.ResourceTypes]: { name: string, icon: Sprite} } = {}, you could do something like:

function Resource () constructor {
  /// @instancevar {string} name
  /// @instancevar {Asset.GMSprite} sprite
}

// Then type-annotate your literal to allow any string as a key

/// @type {Struct<Struct.Resource>}
var resources = {};

// OR, create another constructor with all of the key names specified

function Resources () constructor {
  /// @instancevar {Struct.Resource} water
  /// @instancevar {Struct.Resource} fire
}

/// @type {Struct.Resources}
var resources = {};

(I'm pretty sure that Struct<Struct.Resource> as a type is equivalent to Typescript Record<string, Resource>, but I may be misremembering -- I actually don't do much GameMaker coding!)

Stitch should give you autocomplete help in your JSDoc types, which is very helpful since Feather-style type names are verbose and hard to remember. You can also right-click a symbol to get a handful of "Copy as JSDoc" options, which I think are also in the command palette.

[TeunK]

Aha, so you would only define an empty ctor function with type information contained inside without actually providing any actual content, and then using that as type as a hack to represent something that technically holds those fields.

This works in an immediate context:

Is there a way to maintain this level of information when entering another scope, eg. a function? With @param it is aware of the type, but for some reason it loses the details of the type.

^ Lost autocomplete

^ Does recognise that it's Struct.SkillerUnitSkill but doesn't know its fields

Stitch should give you autocomplete help in your JSDoc types, which is very helpful since Feather-style type names are verbose and hard to remember.

Yeah, completely agree. Projects are fast to grow to a point where they become unmanageable without type information, having to zigzag between docs to double-check their fields. Which is made even worse with the GMS IDE where you visually have to drag and zoom across files. Besides that GM is an amazing tool, so I really appreciate this incentive of adding type support and ability to work in eg. VS Code!

-- Edit:
Actually I see that it is still the same issue when specifying the @type without initializing the variable using the function approach. So it likely doesn't have anything to do with scope:

[adam-coster]

Hmmmm, that SHOULD have worked. Either there's a bug or I've led you astray by forgetting something...

Some things to check:

• Does removing the ///@type {Function} above the constructor change anything? It's not necessary for Stitch or GameMaker, and could be confusing Stitch
• Is this constructor global (defined in a Script)? If it's being defined in an Object then it needs a different typename. The Feather convention for that is pretty weird, but I think Stitch will provide it for you if you right-click and "Copy as type" from the context menu.
• Does it work if you do provide variables, rather than using /// @instancevar (perhaps there's a bug in how I'm handling that)?

If none of that resolves it, please create an issue that includes a minimal, misbehaving code snippet that I can just plop right into my test suite to code against.

[adam-coster]

I did a quick check to see if I can reproduce the issue, but it's working for me!

This is in the context of a script, so the constructor is global. I tried with and without the /// @type {Function}, which didn't have any effect.

If your constructor is in a Script (rather than an Object) then whatever's going on is somehow specific to your project. Unfortunately I have no way to guess what that could be!

For context, my project environment is:

• Windows 11
• GameMaker 2024.200.0.499
• VSCode 1.91.0-insider

[TeunK]

Is this constructor global (defined in a Script)? If it's being defined in an Object then it needs a different typename.

Awesome, this solution works! My above examples were written in Obj:Create (both definition and usage). I'd have thought that especially as long as they're in the same location they'd be able to find eachother. But when moving it into a gml script it does seem to work as expected.

In fact, it seems only the type definition needs to be moved to the script, then the usage can refer to it from anywhere, including inside Obj:Create (and anywhere else I'd assume).

I think Stitch will provide it for you if you right-click and "Copy as type" from the context menu

The "Copy as type" as well as the 2 other options all extract the type Struct.Resources as earlier, so that's unlikely the issue. Perhaps different tags but not sure. I tried a couple of different tags in the Obj:Create but no luck on that.

However as long as I can define these types in scripts publically that should make sense anyway. I don't believe GM provides much control over access scopes, so I can see how it'd make sense to define types publically using the scripts rather than encapsulating them within an GM:Object definition.

Thank you very much for the help!

[adam-coster]

Ah, I must have not yet implemented the Feather-style Object-scoped constructor type names. Whoops!

You're absolutely right that defining your types in Scripts will make them a lot easier to use. That's what we do!