"Guided" types

[that-hatter]

Sometimes, the type signature of a function changes depending on its usage elsewhere in the script.
In the following example, s.spcon takes e,tp,eg,ep,ev,re,r,rp as parameters due to it being set as the condition of trigger effect.

    local e1=Effect.CreateEffect(c)
    e1:SetType(EFFECT_TYPE_SINGLE+EFFECT_TYPE_TRIGGER_O)
    e1:SetCondition(s.spcon)
    c:RegisterEffect(e1)

But if it was set as the condition of a non-activating Special Summon effect, it only takes e,c:

    local e1=Effect.CreateEffect(c)
    e1:SetType(EFFECT_TYPE_FIELD)
    e1:SetCode(EFFECT_SPSUMMON_PROC)
    e1:SetCondition(s.spcon)
    c:RegisterEffect(e1)

This is common for functions passed to SetTarget, SetCondition, SetOperation, and SetValue. It's somewhat unique to ygopro scripting, or at least there doesn't seem to be other projects that attempt to document types that change like this beyond just explaining their usage in the description.

Currently, the only way to sort-of represent this is to document types like ConditionFunction to have different overloads, and each overload specifying what values correspond to them via their description.

[feeshstick]

I can narrow down the signatures as much as i can and map them to the type argument of SetType
This creates a template to work with.
We then modify the template if we see discrepancies.

function s.initial_effect(c)
    local e1 = Effect.CreateEffect(c)
    e1:SetType(EFFECT_TYPE_FIELD)
    e1:SetCode(EFFECT_SPSUMMON_PROC)
    e1:SetCondition(s.spcon)
    c:RegisterEffect(e1)
end

function s.spcon(e,c)
    Effect.CreateEffect(c) -- lookup signature of Effect.CreateEffect @ argument 1 'Card'
    -- no return
    -- signature narrowed to `(a: any, b: Card) => void`
end

{} is a Set, <name>:<value> is a relation

EFFECT_TYPE_FIELD: {
        SetCode: { EFFECT_SPSUMMON_PROC },
        SetCondition: {
            (a: any, b: Card) => void
        }
    }

Let's say:

• SetCode shouldn't exist for Effects of EFFECT_TYPE_FIELD: cut SetCode from it
• SetCondition cannot return void for Effects of EFFECT_TYPE_FIELD: replace it with the proper value
  and so on

tl:dr.: i can approximate the structure based on type and someone corrects all errors

[feeshstick]

This should make it easier to get startet.
Just based on that alone, it'd also require something similar to "overloads", but based on a condition.
Maybe differentiating between the namespace Effect and the return type of Effect.CreateEffect could help?

[that-hatter]

Should they be separate from overloads? I feel like they're fine as overloads, just that the conditions must be formalized in some way, rather than simply putting "this overload is used if ..." in the description.

Maybe differentiating between the namespace Effect and the return type of Effect.CreateEffect could help?

They're already differentiated. The return type of Effect.CreateEffect is the Effect type, separate from the Effect namespace

[that-hatter]

After some discussion with @feeshstick, kinda, sorta settled on putting a "guides" field on params to store information about how to narrow types/overloads following certain passed values.
Example file for a tentative format:

---!function
name: SetType
namespace: Effect
description: |-
  Sets an effect's (Effect e) type. constant.lua contains the list with all valid EffectTypes but other cards' scripts can be used as reference
status:
  index: stable
parameters:
  - name: e
    type: [ Effect ]
    description: (To be added)
  - name: type
    type: [ int ]
    description: (To be added)
    guides:
      - function: SetCondition
        toOverload: 1 # assuming we go with numbered overloads
        when: EFFECT_TYPE_FIELD
      - function: SetCondition
        toOverload: 2
        when: EFFECT_TYPE_IGNITION
tags: [ under-construction ]

Currently not handled: that both calls to SetType and SetCondition should be operating on the same e.

[feeshstick]

Currently not handled: that both calls to SetType and SetCondition should be operating on the same e.

a:SetType(T) is a.SetType(b,T); where a = b.
The first parameter can be skipped in the documentation, A simple flag would indicate a self call.
for example:

• a simple entry like isSelfCallMemberOf: T T: Type like 'Effect', indicating that it's a self-call property of an Effect Type.

That's why i mentioned the differentiation of Namespace and Type. The bottom up approach might be a bit restricting (at least for finding a straightforward solution to everything). It's understandable considering it's also used as front-end data.
Something like this may be possible too:

---!type
name: Effect
supertype: userdata
description: |-
  (To be added)
member:
  - name: SetType
    type: self-call
tags: [ under-construction ]

[that-hatter]

A simple flag would indicate a self call.

For this we're (well, I'm) actually doing something even simpler.
If the first parameter of a function has only one possible type, and that type has the same name as the namespace it's on, it's assumed it can be called with the colon notation. Even if scrapiyard technically doesn't explicitly state the relation between the namespace and the type (see related issue).

It's how I generate the copy-pasteable signature in scrapi-book:

Here, the generated code block uses colon notation instead of saying Effect.SetType(e,type)