[DOCS] Functions and callbacks are too vague.

[rayyanekaputra]

Describe the problem

functions/callbacks are so vague in AnimeJs. i can't tell which callback the doc meant for "timeline" or "animate" because i know these callbacks have their own return type or in easier words the "context" of the timeline.

lets take an example from the doc. timeline.call(callback, position); this is way too vague. i run into a problem where i think it accepts a callback of whatever-callback, but it actually mean a different thing.

const tl = createTimeline()
.call(() => $functionA.innerHTML = 'A', 0) //the example are only for elements/nodelist/etc

this is obvious, duhh. if you want to trigger an event/do something to an element AFTER an animation, you use the .call() method. now what if you do separation of concern on it?

lets create a function

const tl = createTimeline()
const iWantToSetInnerHtml = () => {
  console.log ("Setting now")
  return $functionA.innerHTML = 'A', 0
}

now which version do you think works?

const tl = createTimeline()
const iWantToSetInnerHtml = () => {
console.log ("Setting now")
return $functionA.innerHTML = 'A', 0
}
.call(iWantToSetInnerHtml) //referencing the function 
.call(iWantToSetInnerHtml()) //dont do this, it executes the function and return the value rightaway, thus not a callback

or

const tl = createTimeline()
const iWantToSetInnerHtml = () => {
console.log ("Setting now")
return $functionA.innerHTML = 'A', 0
}
.call(()=>iWantToSetInnerHtml()) //wrap our callback with anime js callback

the answer is the "wrapper" version:

const tl = createTimeline()
const iWantToSetInnerHtml = () => {
console.log ("Setting now")
return $functionA.innerHTML = 'A', 0
}
.call(()=>iWantToSetInnerHtml()) //wrap our callback with anime js callback

both works btw, but the version without wrapper starts NOT according to the timeline. why? because the timeline callback have "Timer" type. so context matters so much here. you can check inside:

//timeline.d.ts
/**
     * @param {Callback<Timer>} callback
     * @param {TimelinePosition} [position]
     * @return {this}
     */
    call(callback: Callback<Timer>, position?: TimelinePosition): this;


//index.d.ts
export type Callback<T> = (self: T, e?: PointerEvent) => any; //culprit

typescript allows you to execute it because both are callbacks with ANY type. so even typescript couldn't catch this misbehavior (not error).

this is the expanded version

const tl = createTimeline()
const iWantToSetInnerHtml = () => {
console.log ("Setting now")
return $functionA.innerHTML = 'A', 0
}
.call(({timelineInstance}, mouseEventhere)=>iWantToSetInnerHtml()) //wrap our callback with anime js callback
//or
.call((self, e)=>{
console.log(e.clientX, e.clientY)
iWantToSetInnerHtml()
self.pause()
}) 

i spent hours looking at the docs and console logging like crazy because it doesnt fire ACCORDING to the timeline.

Provide the suggested modification

we need to make a type strictly differentiating our own callbacks with AnimeJs callbacks. this have caught me in so many ways if i want to do advanced interaction after an animation